کتابخانه Google Identity Services به کاربران این امکان را می‌دهد تا با استفاده از یک مرورگر بازشو یا تغییر مسیر UX یک کد مجوز از Google درخواست کنند. این یک جریان OAuth 2.0 ایمن را آغاز می کند و منجر به یک نشانه دسترسی می شود که برای فراخوانی API های Google از طرف یک کاربر استفاده می شود.
خلاصه جریان کد مجوز OAuth 2.0:
- از یک مرورگر، با حرکتی مانند کلیک روی دکمه، مالک حساب Google یک کد مجوز را از Google درخواست می کند.
- Google پاسخ می‌دهد، یا یک کد مجوز منحصر به فرد را به یک تماس در برنامه وب جاوا اسکریپت شما که در مرورگر کاربر اجرا می‌شود ارسال می‌کند، یا مستقیماً با استفاده از تغییر مسیر مرورگر، نقطه پایانی کد مجوز شما را فراخوانی می‌کند.
- پلتفرم باطن شما میزبان یک نقطه پایانی کد مجوز است و کد را دریافت می کند. پس از تأیید اعتبار، این کد با استفاده از یک درخواست به نقطه پایانی توکن Google با توکن‌های دسترسی و تازه‌سازی هر کاربر مبادله می‌شود.
- Google کد مجوز را تأیید می‌کند، درخواستی را که از پلتفرم امن شما منشأ گرفته است، تأیید می‌کند، توکن‌های دسترسی و تازه‌سازی را صادر می‌کند، و با تماس با نقطه پایانی ورود به سیستم میزبانی شده توسط پلتفرم شما، توکن‌ها را باز می‌گرداند.
- نقطه پایانی ورود به سیستم شما، نشانه‌های دسترسی و تازه‌سازی را دریافت می‌کند، و به‌طور ایمن نشانه تازه‌سازی را برای استفاده بعدی ذخیره می‌کند.
یک کد کلاینت را راه اندازی کنید
متد google.accounts.oauth2.initCodeClient() یک سرویس گیرنده کد را مقداردهی اولیه می کند.
حالت پاپ آپ یا تغییر مسیر
شما می توانید انتخاب کنید که یک کد احراز هویت را با استفاده از جریان کاربر تغییر مسیر یا حالت بازشو به اشتراک بگذارید. با حالت تغییر مسیر، یک نقطه پایانی مجوز OAuth2 را روی سرور خود میزبانی می‌کنید و Google عامل کاربر را به این نقطه پایانی هدایت می‌کند و کد تأیید را به عنوان پارامتر URL به اشتراک می‌گذارد. برای حالت پاپ آپ شما یک کنترل کننده پاسخ به تماس جاوا اسکریپت تعریف می کنید که کد مجوز را به سرور شما ارسال می کند. از حالت پاپ آپ می توان برای ارائه یک تجربه کاربری بدون درز بدون نیاز به خروج بازدیدکنندگان از سایت شما استفاده کرد.
برای مقداردهی اولیه مشتری برای موارد:
جریان UX را تغییر مسیر دهید،
ux_modeرویredirectو مقدارredirect_uriرا به نقطه پایانی کد مجوز پلتفرم خود تنظیم کنید. مقدار باید دقیقاً با یکی از URIهای مجاز تغییر مسیر برای مشتری OAuth 2.0 که در کنسول API پیکربندی کرده اید مطابقت داشته باشد. همچنین باید با قوانین اعتبارسنجی Redirect URI ما مطابقت داشته باشد.جریان UX بازشو،
ux_modeرویpopupتنظیم کنید، و مقدارcallbackرا به نام تابعی که برای ارسال کدهای مجوز به پلتفرم خود استفاده خواهید کرد، تنظیم کنید.
جلوگیری از حملات CSRF
برای کمک به جلوگیری از حملات Cross-Site-Request-Forgery (CSRF) تکنیک های کمی متفاوت برای جریان های UX Redirect و Popup Mode به کار گرفته شده است. برای حالت تغییر مسیر، از پارامتر وضعیت OAuth 2.0 استفاده می شود. برای اطلاعات بیشتر در مورد تولید و اعتبارسنجی پارامتر حالت ، بخش 10.12 جعل درخواست بین‌سایتی RFC6749 را ببینید. با حالت Popup، یک هدر HTTP سفارشی به درخواست‌های خود اضافه می‌کنید و سپس در سرور خود تأیید می‌کنید که با مقدار و مبدا مورد انتظار مطابقت دارد.
یک حالت UX را برای مشاهده قطعه کدی که کد احراز هویت و مدیریت CSRF را نشان می دهد انتخاب کنید:
حالت تغییر مسیر
سرویس گیرنده ای را راه اندازی کنید که در آن Google مرورگر کاربر را به نقطه پایانی احراز هویت شما هدایت می کند و کد احراز هویت را به عنوان پارامتر URL به اشتراک می گذارد.
const client = google.accounts.oauth2.initCodeClient({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
scope: 'https://www.googleapis.com/auth/calendar.readonly',
ux_mode: 'redirect',
redirect_uri: "https://your.domain/code_callback_endpoint",
state: "YOUR_BINDING_VALUE"
});
حالت پاپ آپ
یک کلاینت را راه اندازی کنید که در آن مرورگر کاربر یک کد احراز هویت از Google دریافت کرده و آن را به سرور شما ارسال می کند.
const client = google.accounts.oauth2.initCodeClient({
client_id: 'YOUR_GOOGLE_CLIENT_ID',
scope: 'https://www.googleapis.com/auth/calendar.readonly',
ux_mode: 'popup',
callback: (response) => {
const xhr = new XMLHttpRequest();
xhr.open('POST', code_receiver_uri, 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>
برای این کار لازم است کاربر وارد حساب Google شود و قبل از بازگرداندن کد مجوز به نقطه پایانی تغییر مسیر یا کنترل کننده پاسخ تماس شما، به اشتراک گذاری محدوده های جداگانه رضایت دهد.
مدیریت کد تایید
Google یک کد مجوز منحصر به فرد برای هر کاربر ایجاد می کند که شما آن را دریافت کرده و در سرور پشتیبان خود تأیید می کنید.
برای حالت بازشو، کنترل‌کننده مشخص‌شده توسط callback ، که در مرورگر کاربر اجرا می‌شود، کد مجوز را به نقطه پایانی که توسط پلتفرم شما میزبانی می‌شود، منتقل می‌کند.
برای حالت Redirect، یک درخواست GET به نقطه پایانی مشخص شده توسط redirect_url ارسال می‌شود و کد مجوز را در پارامتر کد URL به اشتراک می‌گذارد. برای دریافت کد مجوز:
اگر پیاده سازی موجود ندارید، یک نقطه پایانی مجوز جدید ایجاد کنید ، یا
نقطه پایانی موجود خود را به‌روزرسانی کنید تا درخواست‌های
GETو پارامترهای URL را بپذیرید. قبلاً از یک درخواستPUTبا مقدار کد مجوز در بار استفاده می شد.
نقطه پایان مجوز
نقطه پایانی کد مجوز شما باید درخواست‌های GET را با این پارامترهای رشته جستجوی URL رسیدگی کند:
| نام | ارزش |
|---|---|
| تایید کننده | درخواست احراز هویت ورود به سیستم کاربر |
| کد | یک کد مجوز OAuth2 ایجاد شده توسط Google |
| hd | دامنه میزبانی شده حساب کاربری |
| سریع | گفتگوی رضایت کاربر |
| محدوده | فهرستی با فاصله از یک یا چند محدوده 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 که حاوی کد مجوز به عنوان یک بار در بدنه درخواست HTTP است:
Request URL: https://www.example.com/auth-code
Request Payload: 4/0AX4XfWhll-BMV82wi4YwbrSaTPaRpUGpKqJ4zBxQldU\_70cnIdh-GJOBZlyHU3MNcz4qaw
درخواست را تایید کنید
در سرور خود موارد زیر را برای جلوگیری از حملات CSRF انجام دهید.
مقدار پارامتر state را برای حالت تغییر مسیر بررسی کنید .
تأیید کنید که هدر X-Requested-With: XmlHttpRequest برای حالت بازشو تنظیم شده است.
تنها در صورتی که ابتدا درخواست کد تأیید را با موفقیت تأیید کرده باشید، باید به دریافت نشانه‌های به‌روزرسانی و دسترسی از Google ادامه دهید.
به توکن‌ها دسترسی پیدا کنید و آن‌ها را تازه‌سازی کنید
پس از اینکه پلتفرم پشتیبان شما یک کد مجوز از Google دریافت کرد و درخواست را تأیید کرد، از کد تأیید برای دسترسی و به‌روزرسانی نشانه‌ها از Google برای برقراری تماس‌های API استفاده کنید.
دستورالعمل‌هایی را که از مرحله 5 شروع می‌شود دنبال کنید: کد مجوز برای به‌روزرسانی و دسترسی به توکن‌های راهنمای Using OAuth 2.0 for Web Server Applications را تعویض کنید.
مدیریت توکن ها
پلتفرم شما به‌طور ایمن توکن‌های تازه‌سازی را ذخیره می‌کند. هنگامی که حساب‌های کاربری حذف می‌شوند یا رضایت کاربر توسط google.accounts.oauth2.revoke یا مستقیماً از https://myaccount.google.com/permissions لغو می‌شود، نشانه‌های به‌روزرسانی ذخیره‌شده را حذف کنید.
به صورت اختیاری، می‌توانید RISC را برای محافظت از حساب‌های کاربری با «محافظت بین حساب‌ها» در نظر بگیرید.
به طور معمول، پلتفرم پشتیبان شما با استفاده از یک نشانه دسترسی، APIهای Google را فراخوانی می کند. اگر برنامه وب شما مستقیماً با Google API از مرورگر کاربر تماس می‌گیرد، باید راهی را برای اشتراک‌گذاری نشانه دسترسی با برنامه وب خود اجرا کنید، انجام این کار خارج از محدوده این راهنما است. هنگام پیروی از این رویکرد و استفاده از Google API Client Library برای جاوا اسکریپت، از gapi.client.SetToken() برای ذخیره موقت نشانه دسترسی در حافظه مرورگر و فعال کردن کتابخانه برای فراخوانی APIهای Google استفاده کنید.