کتابخانه خدمات هویت گوگل (Google Identity Services) کاربران را قادر می‌سازد تا با استفاده از یک جریان پاپ‌آپ یا ریدایرکت UX مبتنی بر مرورگر، از گوگل درخواست کد مجوز کنند. این یک جریان امن OAuth 2.0 را آغاز می‌کند و منجر به یک توکن دسترسی می‌شود که برای فراخوانی APIهای گوگل از طرف کاربر استفاده می‌شود.
خلاصه جریان کد مجوز OAuth 2.0:
- از طریق مرورگر، با حرکتی مانند کلیک روی دکمه، صاحب حساب گوگل از گوگل کد مجوز درخواست می‌کند.
- گوگل پاسخ می‌دهد و یک کد مجوز منحصر به فرد را یا به یک فراخوانی در برنامه وب جاوا اسکریپت شما که در مرورگر کاربر اجرا می‌شود ارسال می‌کند، یا مستقیماً با استفاده از یک تغییر مسیر مرورگر، نقطه پایانی کد مجوز شما را فراخوانی می‌کند.
- پلتفرم بک‌اند شما میزبان یک نقطه پایانی کد مجوز است و کد را دریافت می‌کند. پس از اعتبارسنجی، پلتفرم شما این کد را برای هر کاربر با استفاده از درخواستی به نقطه پایانی توکن گوگل، برای توکن‌های دسترسی و به‌روزرسانی مبادله می‌کند.
- گوگل کد مجوز را اعتبارسنجی می‌کند، تأیید می‌کند که درخواست از پلتفرم امن شما ارسال شده است، توکن‌های دسترسی و به‌روزرسانی را صادر می‌کند و با فراخوانی نقطه پایانی ورود به سیستم که توسط پلتفرم شما میزبانی می‌شود، توکن‌ها را برمی‌گرداند.
- نقطه پایانی ورود شما توکن‌های دسترسی و به‌روزرسانی را دریافت می‌کند و توکن به‌روزرسانی را برای استفاده‌های بعدی به طور ایمن ذخیره می‌کند.
پیش‌نیازها
برای پیکربندی صفحه رضایت OAuth، دریافت شناسه کلاینت و بارگذاری کتابخانه کلاینت، مراحل شرح داده شده در بخش تنظیمات را دنبال کنید.
مقداردهی اولیه یک کلاینت کد
متد google.accounts.oauth2.initCodeClient() یک کلاینت کد را مقداردهی اولیه می‌کند.
حالت پاپ‌آپ یا تغییر مسیر
شما می‌توانید با استفاده از جریان کاربری حالت Redirect یا Popup ، کد احراز هویت را به اشتراک بگذارید. در حالت Redirect، شما یک نقطه پایانی احراز هویت OAuth2 را روی سرور خود میزبانی می‌کنید و گوگل، user-agent را به این نقطه پایانی هدایت می‌کند و کد احراز هویت را به عنوان یک پارامتر URL به اشتراک می‌گذارد. برای حالت Popup، شما یک کنترل‌کننده فراخوانی جاوا اسکریپت تعریف می‌کنید که کد احراز هویت را به سرور شما ارسال می‌کند. می‌توانید از حالت Popup برای ارائه یک تجربه کاربری یکپارچه بدون نیاز به ترک سایت توسط بازدیدکنندگان استفاده کنید.
برای مقداردهی اولیه یک کلاینت برای:
جریان UX را تغییر مسیر دهید،
ux_modeرویredirectو مقدارredirect_uriروی نقطه پایانی کد مجوز پلتفرم خود تنظیم کنید. این مقدار باید دقیقاً با یکی از URI های تغییر مسیر مجاز برای کلاینت OAuth 2.0 که در کنسول Google Cloud پیکربندی کرده‌اید، مطابقت داشته باشد. همچنین باید با قوانین اعتبارسنجی Redirect URI مطابقت داشته باشد.در جریان تجربه کاربری پاپ‌آپ،
ux_modeرویpopupو مقدارcallbackرا روی نام تابعی که برای ارسال کدهای احراز هویت به پلتفرم خود استفاده خواهید کرد، تنظیم کنید. مقدارredirect_uriبه طور پیش‌فرض روی مبدأ صفحه‌ای کهinitCodeClientرا فراخوانی می‌کند، تنظیم می‌شود. جریان از این مقدار بعداً وقتی کد احراز هویت را با توکن دسترسی یا رفرش جایگزین می‌کنید، استفاده می‌کند. به عنوان مثال،https://www.example.com/index.htmlتابعinitCodeClientفراخوانی می‌کند و مبدأ:https://www.example.comمقدارredirect_urlاست.
محافظت در برابر حملات CSRF
جریان‌های تجربه کاربری در حالت‌های Redirect و Popup از تکنیک‌های کمی متفاوت برای جلوگیری از حملات جعل درخواست میان‌سایتی (CSRF) استفاده می‌کنند. برای حالت Redirect، از پارامتر state مربوط به OAuth 2.0 استفاده کنید. برای اطلاعات بیشتر در مورد تولید و اعتبارسنجی پارامتر state ، به بخش RFC6749 بخش 10.12 جعل درخواست میان‌سایتی مراجعه کنید. با حالت Popup، یک هدر HTTP سفارشی به درخواست‌های خود اضافه می‌کنید و سپس در سرور خود تأیید می‌کنید که با مقدار و مبدا مورد انتظار مطابقت دارد.
برای مشاهده قطعه کدی که کد احراز هویت و مدیریت CSRF را نشان می‌دهد، یک حالت UX را انتخاب کنید:
حالت تغییر مسیر
یک کلاینت راه‌اندازی کنید که در آن گوگل مرورگر کاربر را به نقطه پایانی احراز هویت شما هدایت کند و کد احراز هویت را به عنوان پارامتر URL به اشتراک بگذارد.
const client = google.accounts.oauth2.initCodeClient({
client_id: 'YOUR_CLIENT_ID',
scope: 'https://www.googleapis.com/auth/calendar.readonly',
ux_mode: 'redirect',
redirect_uri: 'https://oauth2.example.com/code',
state: 'YOUR_BINDING_VALUE'
});
حالت پاپ‌آپ
یک کلاینت را راه‌اندازی کنید که در آن کاربر جریان احراز هویت را در یک پنجره‌ی محاوره‌ای آغاز می‌کند. پس از رضایت، گوگل کد احراز هویت را با استفاده از یک تابع فراخوانی به مرورگر کاربر برمی‌گرداند. یک درخواست POST از کنترل‌کننده‌ی فراخوانی JS، کد احراز هویت را به یک نقطه‌ی پایانی در سرور backend ارسال می‌کند، جایی که ابتدا آن را تأیید می‌کنید و سپس بقیه‌ی جریان OAuth را تکمیل می‌کنید.
const client = google.accounts.oauth2.initCodeClient({
client_id: 'YOUR_CLIENT_ID',
scope: 'https://www.googleapis.com/auth/calendar.readonly',
ux_mode: 'popup',
callback: (response) => {
const xhr = new XMLHttpRequest();
xhr.open('POST', "https://oauth2.example.com/code", true);
xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
// Set custom header for CRSF
xhr.setRequestHeader('X-Requested-With', 'XmlHttpRequest');
xhr.onload = function() {
console.log('Auth code response: ' + xhr.responseText);
};
xhr.send('code=' + response.code);
},
});
فعال کردن جریان کد OAuth 2.0
برای فعال کردن جریان کاربر، متد requestCode() از سرویس گیرنده کد را فراخوانی کنید:
<button onclick="client.requestCode();">Authorize with Google</button>
این کار مستلزم آن است که کاربر قبل از بازگرداندن کد مجوز به نقطه پایانی تغییر مسیر یا کنترل‌کننده فراخوانی شما، وارد یک حساب گوگل شود و برای اشتراک‌گذاری حوزه‌های فردی رضایت دهد.
مدیریت کد Auth
گوگل یک کد مجوز منحصر به فرد برای هر کاربر ایجاد می‌کند که شما آن را دریافت کرده و در سرور backend خود تأیید می‌کنید.
برای حالت پاپ‌آپ، هندلر مشخص‌شده توسط callback که در مرورگر کاربر اجرا می‌شود، کد مجوز را به یک نقطه پایانی که توسط پلتفرم شما میزبانی می‌شود، ارسال می‌کند.
برای حالت ریدایرکت، گوگل یک درخواست GET به نقطه پایانی مشخص شده توسط redirect_uri ارسال می‌کند و کد مجوز را در پارامتر کد URL به اشتراک می‌گذارد. برای دریافت کد مجوز:
اگر پیاده‌سازی موجود را ندارید، یک نقطه پایانی مجوز جدید ایجاد کنید ، یا
نقطه پایانی موجود خود را برای پذیرش درخواست‌های
GETو پارامترهای URL به‌روزرسانی کنید . پیش از این، گوگل یک درخواستPUTبا مقدار کد مجوز در payload ارسال می‌کرد.
نقطه پایانی مجوز
نقطه پایانی کد مجوز شما باید درخواست‌های GET را با این پارامترهای رشته پرس‌وجوی URL مدیریت کند:
| نام | ارزش |
|---|---|
| نویسنده | درخواست احراز هویت کاربر برای ورود به سیستم |
| کد | یک کد مجوز OAuth2 که توسط گوگل تولید شده است |
| اچ دی | دامنه میزبانی شده حساب کاربری |
| سریع | گفتگوی رضایت کاربر |
| محدوده | فهرستی از یک یا چند محدوده‌ی OAuth2 که باید مجاز شوند، با فاصله از هم جدا شده‌اند. |
| ایالت | متغیر حالت CRSF |
مثال درخواست GET با پارامترهای URL به یک نقطه پایانی به نام auth-code و میزبانی شده توسط example.com:
Request URL: https://www.example.com/auth-code?state=42a7bd822fe32cc56&code=4/0AX4XfWiAvnXLqxlckFUVao8j0zvZUJ06AMgr-n0vSPotHWcn9p-zHCjqwr47KHS_vDvu8w&scope=email%20profile%20https://www.googleapis.com/auth/calendar.readonly%20https://www.googleapis.com/auth/photoslibrary.readonly%20https://www.googleapis.com/auth/contacts.readonly%20openid%20https://www.googleapis.com/auth/userinfo.email%20https://www.googleapis.com/auth/userinfo.profile&authuser=0&hd=example.com&prompt=consent
وقتی جریان کد احراز هویت را با استفاده از کتابخانه‌های قدیمی‌تر جاوا اسکریپت یا با برقراری تماس مستقیم با نقاط انتهایی Google OAuth 2.0 آغاز می‌کنید، گوگل یک درخواست POST ارسال می‌کند.
مثالی از درخواست POST که شامل کد احراز هویت به عنوان یک payload در بدنه درخواست HTTP است:
Request URL: https://www.example.com/auth-code
Request Payload: 4/0AX4XfWhll-BMV82wi4YwbrSaTPaRpUGpKqJ4zBxQldU\_70cnIdh-GJOBZlyHU3MNcz4qaw
درخواست را تأیید کنید
برای جلوگیری از حملات CSRF، موارد زیر را روی سرور خود انجام دهید.
مقدار پارامتر state را برای حالت ریدایرکت بررسی کنید .
تأیید کنید که هدر X-Requested-With: XmlHttpRequest برای حالت پاپ‌آپ موجود است.
سپس فقط در صورتی که ابتدا درخواست کد تأیید را با موفقیت تأیید کرده باشید، باید نسبت به دریافت توکن‌های به‌روزرسانی و دسترسی از گوگل اقدام کنید.
دریافت توکن‌های دسترسی و به‌روزرسانی
پس از اینکه پلتفرم بک‌اند شما کد مجوز را از گوگل دریافت و درخواست را تأیید کرد، از کد مجوز برای دریافت دسترسی و به‌روزرسانی توکن‌ها از گوگل برای برقراری تماس‌های API استفاده کنید.
دستورالعمل‌های شروع از مرحله ۵: تبادل کد مجوز برای به‌روزرسانی و توکن‌های دسترسی راهنمای «استفاده از OAuth 2.0 برای برنامه‌های وب سرور» را دنبال کنید.
مدیریت توکن‌ها
پلتفرم شما توکن‌های به‌روزرسانی را به طور ایمن ذخیره می‌کند. هنگام حذف حساب‌های کاربری، یا لغو رضایت کاربر از طریق google.accounts.oauth2.revoke یا مستقیماً از https://myaccount.google.com/permissions، توکن‌های به‌روزرسانی ذخیره‌شده را حذف کنید.
به صورت اختیاری، می‌توانید RISC را برای محافظت از حساب‌های کاربری با Cross-Account Protection در نظر بگیرید.
معمولاً، پلتفرم بک‌اند شما با استفاده از یک توکن دسترسی، APIهای گوگل را فراخوانی می‌کند. اگر برنامه وب شما مستقیماً APIهای گوگل را از مرورگر کاربر فراخوانی می‌کند، باید روشی برای اشتراک‌گذاری توکن دسترسی با برنامه وب خود پیاده‌سازی کنید، انجام این کار خارج از محدوده این راهنما است. هنگام پیروی از این رویکرد و استفاده از کتابخانه کلاینت API گوگل برای جاوا اسکریپت، از gapi.client.SetToken() برای ذخیره موقت توکن دسترسی در حافظه مرورگر استفاده کنید و کتابخانه را قادر به فراخوانی APIهای گوگل کنید.