APIهای OAuth 2.0 گوگل میتوانند هم برای احراز هویت و هم برای مجوزدهی استفاده شوند. این سند، پیادهسازی OAuth 2.0 ما را برای احراز هویت شرح میدهد که با مشخصات OpenID Connect مطابقت دارد و دارای گواهینامه OpenID است. مستندات موجود در «استفاده از OAuth 2.0 برای دسترسی به APIهای گوگل» نیز برای این سرویس اعمال میشود. اگر میخواهید این پروتکل را به صورت تعاملی بررسی کنید، Google OAuth 2.0 Playground را توصیه میکنیم. برای دریافت کمک در Stack Overflow ، سوالات خود را با برچسب 'google-oauth' مشخص کنید.
راهاندازی OAuth 2.0
قبل از اینکه برنامه شما بتواند از سیستم احراز هویت OAuth 2.0 گوگل برای ورود کاربر استفاده کند، باید یک پروژه در ... تنظیم کنید. Google Cloud Console برای دریافت اعتبارنامههای OAuth 2.0، تنظیم یک URL تغییر مسیر، و (به صورت اختیاری) سفارشیسازی اطلاعات برندسازی که کاربران شما در صفحه رضایت کاربر مشاهده میکنند. همچنین میتوانید از Cloud Console برای ایجاد یک حساب کاربری سرویس، فعال کردن صورتحساب، تنظیم فیلتر و انجام سایر کارها. برای جزئیات بیشتر، به Google Cloud Console کمک کنید .
دریافت اعتبارنامههای OAuth 2.0
برای احراز هویت کاربران و دسترسی به APIهای گوگل، به اعتبارنامههای OAuth 2.0، شامل شناسه کلاینت و رمز کلاینت، نیاز دارید.
برای مشاهده شناسه کلاینت و رمز کلاینت برای یک اعتبارنامه OAuth 2.0 مشخص، روی متن زیر کلیک کنید: انتخاب اعتبارنامه . در پنجرهای که باز میشود، پروژه و اعتبارنامه مورد نظر خود را انتخاب کنید، سپس روی مشاهده کلیک کنید.
یا، شناسه کلاینت و رمز کلاینت خود را ازClients page درCloud Console:
- Go to the Clients page.
- روی نام کلاینت خود یا آیکون ویرایش ( create ) کلیک کنید. شناسه کلاینت و رمز عبور شما در بالای صفحه قرار دارند.
تنظیم یک URL تغییر مسیر
آدرس اینترنتی (URI) ریدایرکتی که در آن تنظیم کردهاید Cloud Console تعیین میکند که گوگل پاسخهای درخواستهای احراز هویت شما را به کجا ارسال کند.
برای ایجاد، مشاهده یا ویرایش URI های تغییر مسیر برای یک اعتبارنامه OAuth 2.0 مشخص، موارد زیر را انجام دهید:
- Go to the Clients page.
- روی کلاینت کلیک کنید.
- مشاهده یا ویرایش آدرسهای اینترنتی (URI) ریدایرکت.
اگر هیچ کلاینتی در صفحه کلاینتها فهرست نشده باشد، پروژه شما فاقد اعتبارنامه OAuth است. برای ایجاد آن، روی ایجاد کلاینت کلیک کنید.
صفحه رضایت کاربر را سفارشی کنید
برای کاربران شما، تجربه احراز هویت OAuth 2.0 شامل یک صفحه رضایتنامه است که اطلاعاتی را که کاربر منتشر میکند و شرایط اعمال شده را شرح میدهد. به عنوان مثال، وقتی کاربر وارد سیستم میشود، ممکن است از او خواسته شود که به برنامه شما اجازه دسترسی به آدرس ایمیل و اطلاعات اولیه حساب خود را بدهد. شما با استفاده از پارامتر scope
که برنامه شما در درخواست احراز هویت خود قرار میدهد، درخواست دسترسی به این اطلاعات را میدهید. همچنین میتوانید از scopeها برای درخواست دسترسی به سایر APIهای Google استفاده کنید.
صفحه رضایت کاربر همچنین اطلاعات مربوط به برند مانند نام محصول، لوگو و آدرس اینترنتی صفحه اصلی شما را ارائه میدهد. شما اطلاعات مربوط به برند را در Cloud Console.
برای فعال کردن صفحه رضایت پروژه خود:
- باز کنید Branding page در Google Cloud Console.
- If prompted, select a project, or create a new one.
- فرم را پر کنید و روی ذخیره کلیک کنید.
کادر گفتگوی رضایت زیر نشان میدهد که کاربر چه چیزی را زمانی که ترکیبی از محدودههای OAuth 2.0 و Google Drive در درخواست وجود دارد، خواهد دید. (این کادر گفتگوی عمومی با استفاده از Google OAuth 2.0 Playground ایجاد شده است، بنابراین شامل اطلاعات برندسازی که در آن تنظیم میشود، نمیشود.) Cloud Console.)

دسترسی به سرویس
گوگل و اشخاص ثالث کتابخانههایی را ارائه میدهند که میتوانید از آنها برای انجام بسیاری از جزئیات پیادهسازی احراز هویت کاربران و دسترسی به APIهای گوگل استفاده کنید. نمونههایی از آنها شامل سرویسهای هویت گوگل و کتابخانههای کلاینت گوگل است که برای پلتفرمهای متنوعی در دسترس هستند.
اگر تصمیم به استفاده از کتابخانه ندارید، دستورالعملهای موجود در ادامهی این سند را دنبال کنید که جریانهای درخواست HTTP تحت کتابخانههای موجود را شرح میدهد.
احراز هویت کاربر
احراز هویت کاربر شامل دریافت یک شناسه (ID Token) و اعتبارسنجی آن است. شناسههای کاربر (ID Token) یک ویژگی استاندارد OpenID Connect هستند که برای استفاده در اشتراکگذاری ادعاهای هویت در اینترنت طراحی شدهاند.
رایجترین رویکردهای مورد استفاده برای احراز هویت کاربر و دریافت توکن شناسایی، جریان "سرور" و جریان "ضمنی" نامیده میشوند. جریان سرور به سرور بکاند یک برنامه اجازه میدهد تا هویت فرد را با استفاده از مرورگر یا دستگاه تلفن همراه تأیید کند. جریان ضمنی زمانی استفاده میشود که یک برنامه سمت کلاینت (معمولاً یک برنامه جاوا اسکریپت که در مرورگر اجرا میشود) نیاز به دسترسی مستقیم به APIها به جای استفاده از سرور بکاند خود داشته باشد.
این سند نحوه انجام جریان سرور برای احراز هویت کاربر را شرح میدهد. جریان ضمنی به دلیل خطرات امنیتی در مدیریت و استفاده از توکنها در سمت کلاینت، به طور قابل توجهی پیچیدهتر است. اگر نیاز به پیادهسازی یک جریان ضمنی دارید، اکیداً توصیه میکنیم از سرویسهای هویت گوگل استفاده کنید.
جریان سرور
مطمئن شوید که برنامه خود را در Cloud Console برای فعال کردن آن جهت استفاده از این پروتکلها و احراز هویت کاربران شما. وقتی کاربری سعی میکند با گوگل وارد سیستم شود، باید:
- ایجاد یک توکن وضعیت ضد جعل
- ارسال درخواست احراز هویت به گوگل
- توکن وضعیت ضد جعل را تأیید کنید
-
code
تبادل برای توکن دسترسی و توکن شناسه - اطلاعات کاربر را از توکن شناسه دریافت کنید
- احراز هویت کاربر
۱. یک توکن وضعیت ضد جعل ایجاد کنید
شما باید با جلوگیری از حملات جعل درخواست، امنیت کاربران خود را حفظ کنید. اولین قدم ایجاد یک توکن جلسه منحصر به فرد است که وضعیت بین برنامه شما و کلاینت کاربر را در خود نگه میدارد. بعداً این توکن جلسه منحصر به فرد را با پاسخ احراز هویت برگردانده شده توسط سرویس ورود Google OAuth مطابقت میدهید تا تأیید کنید که کاربر درخواست را انجام میدهد و نه یک مهاجم مخرب. این توکنها اغلب به عنوان توکنهای جعل درخواست بین سایتی ( CSRF ) شناخته میشوند.
یک انتخاب خوب برای توکن وضعیت، رشتهای حدوداً ۳۰ کاراکتری است که با استفاده از یک مولد اعداد تصادفی با کیفیت بالا ساخته شده است. مورد دیگر، هشی است که با امضای برخی از متغیرهای وضعیت جلسه شما با کلیدی که در پشت صحنه شما مخفی نگه داشته میشود، تولید میشود.
کد زیر نحوهی تولید توکنهای منحصر به فرد session را نشان میدهد.
پی اچ پی
برای استفاده از این نمونه، باید کتابخانه کلاینت APIهای گوگل برای PHP را دانلود کنید.
// Create a state token to prevent request forgery. // Store it in the session for later validation. $state = bin2hex(random_bytes(128/8)); $app['session']->set('state', $state); // Set the client ID, token state, and application name in the HTML while // serving it. return $app['twig']->render('index.html', array( 'CLIENT_ID' => CLIENT_ID, 'STATE' => $state, 'APPLICATION_NAME' => APPLICATION_NAME ));
جاوا
برای استفاده از این نمونه، باید کتابخانه کلاینت APIهای گوگل برای جاوا را دانلود کنید.
// Create a state token to prevent request forgery. // Store it in the session for later validation. String state = new BigInteger(130, new SecureRandom()).toString(32); request.session().attribute("state", state); // Read index.html into memory, and set the client ID, // token state, and application name in the HTML before serving it. return new Scanner(new File("index.html"), "UTF-8") .useDelimiter("\\A").next() .replaceAll("[{]{2}\\s*CLIENT_ID\\s*[}]{2}", CLIENT_ID) .replaceAll("[{]{2}\\s*STATE\\s*[}]{2}", state) .replaceAll("[{]{2}\\s*APPLICATION_NAME\\s*[}]{2}", APPLICATION_NAME);
پایتون
برای استفاده از این نمونه، باید کتابخانه کلاینت APIهای گوگل برای پایتون را دانلود کنید.
# Create a state token to prevent request forgery. # Store it in the session for later validation. state = hashlib.sha256(os.urandom(1024)).hexdigest() session['state'] = state # Set the client ID, token state, and application name in the HTML while # serving it. response = make_response( render_template('index.html', CLIENT_ID=CLIENT_ID, STATE=state, APPLICATION_NAME=APPLICATION_NAME))
۲. ارسال درخواست احراز هویت به گوگل
مرحله بعدی، تشکیل یک درخواست HTTPS GET
با پارامترهای URI مناسب است. به استفاده از HTTPS به جای HTTP در تمام مراحل این فرآیند توجه کنید؛ اتصالات HTTP رد میشوند. شما باید URI پایه را از سند Discovery با استفاده از مقدار فراداده authorization_endpoint
بازیابی کنید. بحث زیر فرض میکند که URI پایه https://accounts.google.com/o/oauth2/v2/auth
است.
برای یک درخواست اولیه، پارامترهای زیر را مشخص کنید:
-
client_id
که از آن دریافت میکنید Cloud ConsoleClients page. -
response_type
، که در یک درخواست جریان کد مجوز پایه بایدcode
باشد. (برای اطلاعات بیشتر بهresponse_type
مراجعه کنید.) -
scope
، که در یک درخواست اولیه بایدopenid email
باشد. (برای اطلاعات بیشتر بهscope
مراجعه کنید.) -
redirect_uri
باید نقطه پایانی HTTP روی سرور شما باشد که پاسخ را از گوگل دریافت میکند. مقدار آن باید دقیقاً با یکی از URI های ریدایرکت مجاز برای کلاینت OAuth 2.0 که در مرحله قبل پیکربندی کردهاید، مطابقت داشته باشد. Cloud ConsoleCredentials pageاگر این مقدار با یک URI مجاز مطابقت نداشته باشد، درخواست با خطایredirect_uri_mismatch
با شکست مواجه میشود. -
state
باید شامل مقدار توکن جلسه منحصر به فرد ضد جعل و همچنین هرگونه اطلاعات دیگری باشد که برای بازیابی زمینه هنگام بازگشت کاربر به برنامه شما لازم است، مثلاً URL شروع. (برای اطلاعات بیشتر بهstate
مراجعه کنید.) -
nonce
یک مقدار تصادفی است که توسط برنامه شما تولید میشود و در صورت وجود، محافظت در برابر تکرار را فعال میکند. -
login_hint
میتواند آدرس ایمیل کاربر یاsub
باشد که معادل شناسه گوگل کاربر است. اگرlogin_hint
را ارائه ندهید و کاربر وارد سیستم شده باشد، صفحه رضایت شامل درخواستی برای تأیید انتشار آدرس ایمیل کاربر در برنامه شما میشود. (برای اطلاعات بیشتر بهlogin_hint
مراجعه کنید.) - از پارامتر
hd
برای بهینهسازی جریان OpenID Connect برای کاربران یک دامنه خاص مرتبط با یک سازمان Google Workspace یا Cloud استفاده کنید (برای اطلاعات بیشتر بهhd
مراجعه کنید).
در اینجا مثالی از یک URI احراز هویت کامل OpenID Connect، با پرش به خط بعد و فاصله برای خوانایی بیشتر، آورده شده است:
https://accounts.google.com/o/oauth2/v2/auth? response_type=code& client_id=424911365001.apps.googleusercontent.com& scope=openid%20email& redirect_uri=https%3A//oauth2.example.com/code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2-login-demo.example.com%2FmyHome& login_hint=jsmith@example.com& nonce=0394852-3190485-2490358& hd=example.com
اگر برنامه شما اطلاعات جدیدی درباره کاربران درخواست کند، یا اگر برنامه شما دسترسی به حسابی را درخواست کند که قبلاً تأیید نکردهاند، کاربران موظف به دادن رضایت هستند.
۳. توکن وضعیت ضد جعل را تأیید کنید
پاسخ به redirect_uri
که در درخواست مشخص کردهاید ارسال میشود. همه پاسخها در رشته پرسوجو برگردانده میشوند:
https://oauth2.example.com/code?state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foa2cb.example.com%2FmyHome&code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&scope=openid%20email%20https://www.googleapis.com/auth/userinfo.email
در سرور، باید تأیید کنید که state
دریافتی از گوگل با توکن جلسهای که در مرحله ۱ ایجاد کردهاید، مطابقت دارد. این تأیید رفت و برگشتی به تأیید این موضوع کمک میکند که کاربر، نه یک اسکریپت مخرب، درخواست را ارسال میکند.
کد زیر تایید توکنهای نشستی که در مرحله ۱ ایجاد کردهاید را نشان میدهد:
پی اچ پی
برای استفاده از این نمونه، باید کتابخانه کلاینت APIهای گوگل برای PHP را دانلود کنید.
// Ensure that there is no request forgery going on, and that the user // sending us this connect request is the user that was supposed to. if ($request->get('state') != ($app['session']->get('state'))) { return new Response('Invalid state parameter', 401); }
جاوا
برای استفاده از این نمونه، باید کتابخانه کلاینت APIهای گوگل برای جاوا را دانلود کنید.
// Ensure that there is no request forgery going on, and that the user // sending us this connect request is the user that was supposed to. if (!request.queryParams("state").equals( request.session().attribute("state"))) { response.status(401); return GSON.toJson("Invalid state parameter."); }
پایتون
برای استفاده از این نمونه، باید کتابخانه کلاینت APIهای گوگل برای پایتون را دانلود کنید.
# Ensure that the request is not a forgery and that the user sending # this connect request is the expected user. if request.args.get('state', '') != session['state']: response = make_response(json.dumps('Invalid state parameter.'), 401) response.headers['Content-Type'] = 'application/json' return response
۴. code
تبادل برای توکن دسترسی و توکن شناسه
پاسخ شامل یک پارامتر code
، یک کد مجوز یکبار مصرف است که سرور شما میتواند آن را با یک توکن دسترسی و توکن شناسه مبادله کند. سرور شما این مبادله را با ارسال یک درخواست HTTPS POST
انجام میدهد. درخواست POST
به نقطه پایانی توکن ارسال میشود که شما باید آن را از سند Discovery با استفاده از مقدار فراداده token_endpoint
بازیابی کنید. بحث زیر فرض میکند که نقطه پایانی https://oauth2.googleapis.com/token
است. درخواست باید شامل پارامترهای زیر در بدنه POST
باشد:
فیلدها | |
---|---|
code | کد مجوزی که از درخواست اولیه برگردانده میشود. |
client_id | شناسه کلاینتی که از ... دریافت میکنید Cloud ConsoleClients pageهمانطور که در بخش «دریافت اعتبارنامههای OAuth 2.0» توضیح داده شده است. |
client_secret | راز مشتری که از آن به دست میآورید Cloud ConsoleClients pageهمانطور که در بخش «دریافت اعتبارنامههای OAuth 2.0» توضیح داده شده است. |
redirect_uri | یک URI تغییر مسیر مجاز برای client_id داده شده که در Cloud ConsoleClients pageهمانطور که در تنظیم یک URL تغییر مسیر توضیح داده شده است. |
grant_type | این فیلد باید حاوی مقداری از authorization_code باشد، همانطور که در مشخصات OAuth 2.0 تعریف شده است . |
درخواست واقعی ممکن است مانند مثال زیر باشد:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7& client_id=your-client-id& client_secret=your-client-secret& redirect_uri=https%3A//oauth2.example.com/code& grant_type=authorization_code
پاسخ موفقیتآمیز به این درخواست شامل فیلدهای زیر در یک آرایه JSON است:
فیلدها | |
---|---|
access_token | توکنی که میتواند به API گوگل ارسال شود. |
expires_in | طول عمر باقی مانده از توکن دسترسی بر حسب ثانیه. |
id_token | یک JWT که حاوی اطلاعات هویتی کاربر است و توسط گوگل به صورت دیجیتالی امضا شده است. |
scope | دامنههای دسترسی اعطا شده توسط access_token به صورت فهرستی از رشتههای جدا شده با فاصله و حساس به حروف بزرگ و کوچک بیان میشوند. |
token_type | نوع توکن برگردانده شده را مشخص میکند. در حال حاضر، این فیلد همیشه مقدار Bearer را دارد. |
refresh_token | (اختیاری) این فیلد فقط در صورتی وجود دارد که پارامتر |
۵. اطلاعات کاربر را از توکن شناسه دریافت کنید
یک شناسه توکن (ID Token) یک JWT (نشانه وب JSON) است، یعنی یک شیء JSON رمزگذاری شده با Base64 که به صورت رمزنگاری امضا شده است. معمولاً بسیار مهم است که قبل از استفاده از یک شناسه توکن، آن را اعتبارسنجی کنید، اما از آنجایی که شما مستقیماً با گوگل از طریق یک کانال HTTPS بدون واسطه ارتباط برقرار میکنید و از رمز کلاینت خود برای احراز هویت خود به گوگل استفاده میکنید، میتوانید مطمئن باشید که شناسه توکنی که دریافت میکنید واقعاً از گوگل میآید و معتبر است. اگر سرور شما شناسه توکن را به سایر اجزای برنامه شما منتقل میکند، بسیار مهم است که سایر اجزا قبل از استفاده از آن، آن را اعتبارسنجی کنند .
از آنجایی که اکثر کتابخانههای API اعتبارسنجی را با کار رمزگشایی مقادیر کدگذاری شده با base64url و تجزیه JSON درون آن ترکیب میکنند، احتمالاً در نهایت هنگام دسترسی به ادعاهای موجود در توکن ID، توکن را اعتبارسنجی خواهید کرد.
بار دادهی یک توکن شناسایی
یک شناسه توکن (ID token) یک شیء JSON است که شامل مجموعهای از جفتهای نام/مقدار است. در اینجا مثالی آورده شده است که برای خوانایی بیشتر فرمتبندی شده است:
{ "iss": "https://accounts.google.com", "azp": "1234987819200.apps.googleusercontent.com", "aud": "1234987819200.apps.googleusercontent.com", "sub": "10769150350006150715113082367", "at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q", "hd": "example.com", "email": "jsmith@example.com", "email_verified": "true", "iat": 1353601026, "exp": 1353604926, "nonce": "0394852-3190485-2490358" }
توکنهای شناسه گوگل ممکن است شامل فیلدهای زیر باشند (که به عنوان ادعاها شناخته میشوند):
ادعا | ارائه شده | توضیحات |
---|---|---|
aud | همیشه | مخاطبی که این توکن شناسه برای آن در نظر گرفته شده است. این توکن باید یکی از شناسههای کلاینت OAuth 2.0 برنامه شما باشد. |
exp | همیشه | زمان انقضایی که در آن یا پس از آن توکن شناسه نباید پذیرفته شود. در واحد زمان یونیکس (ثانیه صحیح) نمایش داده میشود. |
iat | همیشه | زمان صدور توکن شناسه. نمایش داده شده بر اساس زمان یونیکس (ثانیه صحیح). |
iss | همیشه | شناسه صادرکننده برای صادرکننده پاسخ. همیشه برای توکنهای شناسه گوگل https://accounts.google.com یا accounts.google.com باشد. |
sub | همیشه | یک شناسه برای کاربر، منحصر به فرد در بین تمام حسابهای گوگل و هرگز دوباره استفاده نمیشود. یک حساب گوگل میتواند چندین آدرس ایمیل در مقاطع زمانی مختلف داشته باشد، اما مقدار sub هرگز تغییر نمیکند. sub در برنامه خود به عنوان کلید شناسه منحصر به فرد برای کاربر استفاده کنید. حداکثر طول ۲۵۵ کاراکتر ASCII حساس به حروف بزرگ و کوچک. |
at_hash | هش توکن دسترسی. اعتبارسنجی میکند که توکن دسترسی به توکن هویت متصل است. اگر توکن شناسه با مقدار access_token در جریان سرور صادر شود، این ادعا همیشه شامل میشود. این ادعا میتواند به عنوان یک مکانیسم جایگزین برای محافظت در برابر حملات جعل درخواست بین سایتی استفاده شود، اما اگر مراحل ۱ و ۳ را دنبال کنید، نیازی به تأیید توکن دسترسی نیست. | |
azp | client_id ارائهدهندهی مجاز. این ادعا فقط زمانی مورد نیاز است که طرف درخواستکنندهی توکن شناسه با مخاطب توکن شناسه یکسان نباشد. این مورد ممکن است در گوگل برای برنامههای ترکیبی صدق کند که در آن یک برنامهی وب و برنامهی اندروید client_id OAuth 2.0 متفاوتی دارند اما پروژهی APIهای گوگل یکسانی را به اشتراک میگذارند. | |
email | آدرس ایمیل کاربر. فقط در صورتی ارائه میشود که محدوده email را در درخواست خود لحاظ کرده باشید. مقدار این ادعا ممکن است مختص این حساب نباشد و با گذشت زمان تغییر کند، بنابراین نباید از این مقدار به عنوان شناسه اصلی برای پیوند به رکورد کاربر خود استفاده کنید. همچنین نمیتوانید برای شناسایی کاربران سازمانهای Google Workspace یا Cloud به دامنه ادعای email تکیه کنید؛ در عوض از ادعای hd استفاده کنید. | |
email_verified | اگر آدرس ایمیل کاربر تأیید شده باشد، مقدار True و در غیر این صورت مقدار False برمیگرداند. | |
family_name | نام خانوادگی یا نام خانوادگی کاربر. ممکن است در صورت وجود ادعای name ، ارائه شود. | |
given_name | نام (های) کاربر یا نام کوچک او. ممکن است در صورت وجود ادعای name ارائه شود. | |
hd | دامنه مرتبط با سازمان فضای کاری گوگل یا فضای ابری کاربر. فقط در صورتی ارائه میشود که کاربر متعلق به یک سازمان فضای ابری گوگل باشد. هنگام محدود کردن دسترسی به یک منبع فقط به اعضای دامنههای خاص، باید این ادعا را بررسی کنید. عدم وجود این ادعا نشان میدهد که حساب متعلق به دامنه میزبانی شده توسط گوگل نیست. | |
locale | زبان کاربر، که با برچسب زبان BCP 47 نمایش داده میشود. ممکن است در صورت وجود ادعای name ، ارائه شود. | |
name | نام کامل کاربر، به صورت قابل نمایش. ممکن است در موارد زیر ارائه شود:
وقتی ادعاهای | |
nonce | مقدار nonce ارائه شده توسط برنامه شما در درخواست احراز هویت. شما باید با ارائه این مقدار فقط یک بار، از حملات بازپخش جلوگیری کنید. | |
picture | آدرس اینترنتی (URL) تصویر پروفایل کاربر. ممکن است در موارد زیر ارائه شود:
وقتی ادعاهای | |
profile | آدرس اینترنتی صفحه پروفایل کاربر. ممکن است در موارد زیر ارائه شود:
وقتی ادعاهای |
۶. احراز هویت کاربر
پس از دریافت اطلاعات کاربر از توکن شناسه، باید پایگاه داده کاربر برنامه خود را جستجو کنید. اگر کاربر از قبل در پایگاه داده شما وجود دارد، در صورتی که تمام الزامات ورود به سیستم توسط پاسخ API گوگل برآورده شده باشد، باید یک جلسه برنامه برای آن کاربر شروع کنید.
اگر کاربر در پایگاه داده کاربر شما وجود ندارد، باید کاربر را به جریان ثبت نام کاربر جدید خود هدایت کنید. ممکن است بتوانید بر اساس اطلاعاتی که از گوگل دریافت میکنید، کاربر را به صورت خودکار ثبت نام کنید، یا حداقل میتوانید بسیاری از فیلدهای مورد نیاز در فرم ثبت نام خود را از قبل پر کنید. علاوه بر اطلاعات موجود در شناسه، میتوانید اطلاعات پروفایل کاربر اضافی را در نقاط پایانی پروفایل کاربر ما دریافت کنید.
مباحث پیشرفته
بخشهای بعدی، API گوگل OAuth 2.0 را با جزئیات بیشتری شرح میدهند. این اطلاعات برای توسعهدهندگانی در نظر گرفته شده است که نیازهای پیشرفتهای در مورد احراز هویت و مجوزدهی دارند.
دسترسی به سایر API های گوگل
یکی از مزایای استفاده از OAuth 2.0 برای احراز هویت این است که برنامه شما میتواند همزمان با احراز هویت کاربر، اجازه استفاده از سایر APIهای گوگل (مانند YouTube، Google Drive، Calendar یا Contacts) را از طرف کاربر دریافت کند. برای انجام این کار، سایر حوزههای مورد نیاز خود را در درخواست احراز هویتی که به گوگل ارسال میکنید، لحاظ کنید. به عنوان مثال، برای اضافه کردن گروه سنی کاربر به درخواست احراز هویت خود، یک پارامتر حوزه از openid email https://www.googleapis.com/auth/profile.agerange.read
ارسال کنید. کاربر به طور مناسب در صفحه رضایتنامه از او سوال میشود. توکن دسترسی که از گوگل دریافت میکنید، به برنامه شما اجازه میدهد به تمام APIهای مربوط به حوزههای دسترسی که درخواست کردهاید و به شما اعطا شده است، دسترسی داشته باشد.
توکنهای تازهسازی
در درخواست خود برای دسترسی به API، میتوانید درخواست کنید که یک توکن بهروزرسانی (refresh token) در طول تبادل code
بازگردانده شود. توکن بهروزرسانی به برنامه شما امکان دسترسی مداوم به APIهای گوگل را در زمانی که کاربر در برنامه شما حضور ندارد، میدهد. برای درخواست توکن بهروزرسانی، پارامتر access_type
را در درخواست احراز هویت خود روی offline
تنظیم کنید.
ملاحظات:
- حتماً توکن بهروزرسانی را به صورت ایمن و دائمی ذخیره کنید، زیرا فقط اولین باری که جریان تبادل کد را انجام میدهید میتوانید توکن بهروزرسانی را دریافت کنید.
- محدودیتهایی در تعداد توکنهای بهروزرسانی صادر شده وجود دارد: یک محدودیت برای هر ترکیب کلاینت/کاربر، و محدودیت دیگر برای هر کاربر در تمام کلاینتها. اگر برنامه شما توکنهای بهروزرسانی زیادی درخواست کند، ممکن است با این محدودیتها مواجه شود، که در این صورت توکنهای بهروزرسانی قدیمیتر از کار میافتند.
برای اطلاعات بیشتر، به بهروزرسانی توکن دسترسی (دسترسی آفلاین) مراجعه کنید.
درخواست رضایت مجدد
شما میتوانید با تنظیم پارامتر prompt
به صورت consent
در درخواست احراز هویت خود، از کاربر بخواهید که برنامه شما را مجدداً تأیید کند. وقتی prompt=consent
گنجانده شده باشد، صفحه رضایت هر بار که برنامه شما درخواست تأیید دامنههای دسترسی را میکند، نمایش داده میشود، حتی اگر قبلاً همه دامنهها به پروژه Google API شما اعطا شده باشند. به همین دلیل، prompt=consent
فقط در صورت لزوم وارد کنید.
برای اطلاعات بیشتر در مورد پارامتر prompt
، به prompt
در جدول پارامترهای Authentication URI مراجعه کنید.
پارامترهای URI احراز هویت
جدول زیر توضیحات کاملتری از پارامترهای پذیرفتهشده توسط API احراز هویت OAuth 2.0 گوگل ارائه میدهد.
پارامتر | مورد نیاز | توضیحات |
---|---|---|
client_id | (الزامی) | رشته شناسه کلاینت که از آن دریافت میکنید Cloud ConsoleClients pageهمانطور که در بخش «دریافت اعتبارنامههای OAuth 2.0» توضیح داده شده است. |
nonce | (الزامی) | یک مقدار تصادفی که توسط برنامه شما تولید میشود و محافظت در برابر تکرار را فعال میکند. |
response_type | (الزامی) | اگر مقدار code باشد، یک جریان کد مجوز پایه راهاندازی میشود که برای دریافت توکنها نیاز به یک POST به نقطه انتهایی توکن دارد. اگر مقدار token id_token یا id_token token باشد، یک جریان ضمنی راهاندازی میشود که نیاز به استفاده از جاوا اسکریپت در URI تغییر مسیر برای بازیابی توکنها از شناسه #fragment URI دارد. |
redirect_uri | (الزامی) | تعیین میکند که پاسخ به کجا ارسال شود. مقدار این پارامتر باید دقیقاً با یکی از مقادیر مجاز تغییر مسیر که در Cloud ConsoleClients page (شامل طرح HTTP یا HTTPS، حروف بزرگ و کوچک، و علامت '/' در صورت وجود). |
scope | (الزامی) | پارامتر scope باید با مقدار اگر مقدار دامنه اگر مقدار دامنه علاوه بر این محدودههای مختص OpenID، آرگومان scope شما میتواند شامل مقادیر scope دیگری نیز باشد. همه مقادیر scope باید با فاصله از هم جدا شوند. برای مثال، اگر میخواهید به ازای هر فایل به Google Drive یک کاربر دسترسی داشته باشید، پارامتر scope شما میتواند برای اطلاعات بیشتر در مورد محدودههای موجود، به محدودههای OAuth 2.0 برای APIهای گوگل یا مستندات مربوط به API گوگلی که میخواهید استفاده کنید، مراجعه کنید. |
state | (اختیاری، اما اکیداً توصیه میشود) | یک رشتهی مبهم که در پروتکل به صورت رفت و برگشتی برگردانده میشود؛ به عبارت دیگر، در جریان Basic به عنوان یک پارامتر URI و در جریان Implicit به عنوان شناسهی |
access_type | (اختیاری) | مقادیر مجاز offline و online هستند. تأثیر آن در دسترسی آفلاین مستند شده است؛ اگر یک توکن دسترسی درخواست شود، کلاینت توکن بهروزرسانی دریافت نمیکند مگر اینکه مقدار offline مشخص شده باشد. |
display | (اختیاری) | یک مقدار رشتهای ASCII برای مشخص کردن نحوه نمایش صفحات رابط کاربری احراز هویت و رضایت توسط سرور تأیید. مقادیر زیر مشخص شده و توسط سرورهای گوگل پذیرفته میشوند، اما هیچ تأثیری بر رفتار جریان پروتکل ندارند: page ، popup ، touch و wap . |
hd | (اختیاری) | فرآیند ورود به سیستم برای حسابهای متعلق به یک سازمان Google Cloud را ساده کنید. با درج دامنه سازمان Google Cloud (به عنوان مثال، mycollege.edu )، میتوانید مشخص کنید که رابط کاربری انتخاب حساب باید برای حسابهای آن دامنه بهینه شود. برای بهینهسازی کلی برای حسابهای سازمان Google Cloud به جای فقط یک دامنه سازمان Google Cloud، مقداری مانند ستاره ( برای کنترل اینکه چه کسی میتواند به برنامه شما دسترسی داشته باشد، به این بهینهسازی رابط کاربری تکیه نکنید، زیرا درخواستهای سمت کلاینت قابل تغییر هستند. حتماً اعتبارسنجی کنید که توکن شناسه بازگشتی دارای مقدار |
include_granted_scopes | (اختیاری) | اگر به این پارامتر مقدار true داده شود و درخواست مجوز اعطا شود، مجوز شامل هرگونه مجوز قبلی اعطا شده به این ترکیب کاربر/برنامه برای سایر حوزهها نیز خواهد بود؛ به مجوز افزایشی مراجعه کنید.توجه داشته باشید که نمیتوانید با جریان برنامه نصبشده، احراز هویت افزایشی انجام دهید. |
login_hint | (اختیاری) | وقتی برنامه شما بداند که قصد احراز هویت کدام کاربر را دارد، میتواند این پارامتر را به عنوان یک راهنما به سرور احراز هویت ارائه دهد. ارسال این راهنما، انتخاب حساب کاربری را متوقف میکند و یا کادر ایمیل را در فرم ورود از قبل پر میکند، یا جلسه مناسب را انتخاب میکند (اگر کاربر از چندین ورود استفاده میکند)، که میتواند به شما کمک کند از مشکلاتی که در صورت ورود برنامه شما به حساب کاربری اشتباه رخ میدهد، جلوگیری کنید. مقدار میتواند یک آدرس ایمیل یا sub رشته باشد که معادل شناسه گوگل کاربر است. |
prompt | (اختیاری) | فهرستی از مقادیر رشتهای که با فاصله از هم جدا شدهاند و مشخص میکنند که آیا سرور تأیید، کاربر را برای تأیید مجدد و رضایت ترغیب میکند یا خیر. مقادیر ممکن عبارتند از:
اگر هیچ مقداری مشخص نشده باشد و کاربر قبلاً اجازه دسترسی نداده باشد، صفحه رضایت به کاربر نشان داده میشود. |
hl | (اختیاری) | یک برچسب زبان BCP 47 که برای تعیین زبان نمایش صفحات ورود به سیستم، انتخاب حساب کاربری و رضایتنامه استفاده میشود. اگر این پارامتر ارائه نشود، زبان به طور پیشفرض روی تنظیمات حساب گوگل یا مرورگر کاربر تنظیم میشود. برای مثال، برای درخواست رابط کاربری به زبان انگلیسی بریتانیایی، پارامتر را روی en-GB تنظیم کنید. |
اعتبارسنجی یک توکن شناسه
شما باید تمام توکنهای شناسه (ID tokens) را روی سرور خود اعتبارسنجی کنید، مگر اینکه مطمئن باشید که آنها مستقیماً از گوگل آمدهاند. به عنوان مثال، سرور شما باید هر توکن شناسهای را که از برنامههای کلاینت شما دریافت میکند، معتبر بداند.
موارد زیر موقعیتهای رایجی هستند که ممکن است در آنها توکنهای شناسه را به سرور خود ارسال کنید:
- ارسال توکنهای شناسه به همراه درخواستهایی که نیاز به احراز هویت دارند. توکنهای شناسه به شما میگویند که کاربر خاص درخواستکننده کیست و این توکن شناسه برای کدام کلاینت اعطا شده است.
توکنهای شناسه حساس هستند و در صورت رهگیری میتوانند مورد سوءاستفاده قرار گیرند. شما باید با ارسال این توکنها فقط از طریق HTTPS و فقط با استفاده از دادههای POST یا درون هدرهای درخواست، اطمینان حاصل کنید که به طور ایمن مدیریت میشوند. اگر توکنهای شناسه را روی سرور خود ذخیره میکنید، باید آنها را نیز به طور ایمن ذخیره کنید.
یکی از چیزهایی که توکنهای شناسه را مفید میکند این واقعیت است که میتوانید آنها را در اجزای مختلف برنامه خود منتقل کنید. این اجزا میتوانند از یک توکن شناسه به عنوان یک مکانیسم احراز هویت سبک استفاده کنند که برنامه و کاربر را تأیید میکند. اما قبل از اینکه بتوانید از اطلاعات موجود در توکن شناسه استفاده کنید یا به عنوان ادعایی مبنی بر تأیید هویت کاربر به آن تکیه کنید، باید آن را اعتبارسنجی کنید.
اعتبارسنجی یک شناسه توکن مستلزم چندین مرحله است:
- تأیید کنید که توکن شناسه به درستی توسط صادرکننده امضا شده است. توکنهای صادر شده توسط گوگل با استفاده از یکی از گواهیهای موجود در URI مشخص شده در مقدار فراداده
jwks_uri
سند Discovery امضا شدهاند. - تأیید کنید که مقدار ادعای
iss
در شناسه توکن برابر باhttps://accounts.google.com
یاaccounts.google.com
باشد. - تأیید کنید که مقدار
aud
claim در شناسه شناسه با شناسه کلاینت برنامه شما برابر است. - تأیید کنید که زمان انقضا (
exp
claim) توکن شناسه (ID token) نگذشته باشد. - اگر در درخواست، مقدار پارامتر hd را مشخص کردهاید، تأیید کنید که شناسه توکن دارای یک ادعای
hd
است که با دامنه پذیرفتهشده مرتبط با یک سازمان Google Cloud مطابقت دارد.
مراحل ۲ تا ۵ فقط شامل مقایسه رشتهها و تاریخها میشوند که کاملاً سرراست هستند، بنابراین در اینجا به جزئیات آنها نمیپردازیم.
مرحله اول پیچیدهتر است و شامل بررسی امضای رمزنگاری شده میشود. برای اشکالزدایی ، میتوانید از نقطه پایانی tokeninfo
گوگل برای مقایسه با پردازش محلی پیادهسازی شده روی سرور یا دستگاه خود استفاده کنید. فرض کنید مقدار توکن ID شما XYZ123
است. سپس باید آدرس اینترنتی https://oauth2.googleapis.com/tokeninfo?id_token= XYZ123
را تغییر دهید. اگر امضای توکن معتبر باشد، پاسخ، JWT payload در قالب شیء JSON رمزگشایی شده آن خواهد بود.
نقطه پایانی tokeninfo
برای اشکالزدایی مفید است، اما برای اهداف عملیاتی، کلیدهای عمومی گوگل را از نقطه پایانی keys بازیابی کنید و اعتبارسنجی را به صورت محلی انجام دهید. شما باید URI کلیدها را از سند Discovery با استفاده از مقدار فراداده jwks_uri
بازیابی کنید. درخواستها به نقطه پایانی اشکالزدایی ممکن است محدود شوند یا در غیر این صورت با خطاهای متناوب مواجه شوند.
از آنجایی که گوگل کلیدهای عمومی خود را به ندرت تغییر میدهد، میتوانید آنها را با استفاده از دستورالعملهای کش پاسخ HTTP ذخیره کنید و در اکثر موارد، اعتبارسنجی محلی را بسیار کارآمدتر از استفاده از نقطه پایانی tokeninfo
انجام دهید. این اعتبارسنجی نیاز به بازیابی و تجزیه گواهیها و انجام فراخوانیهای رمزنگاری مناسب برای بررسی امضا دارد. خوشبختانه، کتابخانههای اشکالزداییشده خوبی در زبانهای مختلف برای انجام این کار وجود دارد (به jwt.io مراجعه کنید).
دریافت اطلاعات پروفایل کاربر
برای به دست آوردن اطلاعات پروفایل بیشتر در مورد کاربر، میتوانید از توکن دسترسی (که برنامه شما در طول جریان احراز هویت دریافت میکند) و استاندارد OpenID Connect استفاده کنید:
برای اینکه با OpenID سازگار باشید، باید مقادیر دامنه
openid profile
را در درخواست احراز هویت خود لحاظ کنید.اگر میخواهید آدرس ایمیل کاربر نیز لحاظ شود، میتوانید یک مقدار دامنه اضافی برای
email
تعیین کنید. برای مشخص کردن همزمانprofile
وemail
، میتوانید پارامتر زیر را در URI درخواست احراز هویت خود وارد کنید:scope=openid%20profile%20email
- توکن دسترسی خود را به هدر مجوز اضافه کنید و یک درخواست HTTPS
GET
به نقطه پایانی userinfo ارسال کنید، که باید آن را از سند Discovery با استفاده از مقدار فرادادهuserinfo_endpoint
بازیابی کنید. پاسخ userinfo شامل اطلاعاتی در مورد کاربر است، همانطور که درOpenID Connect Standard Claims
و مقدار فرادادهclaims_supported
سند Discovery توضیح داده شده است. کاربران یا سازمانهای آنها میتوانند فیلدهای خاصی را ارائه یا از ارائه آنها خودداری کنند، بنابراین ممکن است اطلاعات مربوط به هر فیلد را برای محدودههای دسترسی مجاز خود دریافت نکنید.
سند دیسکاوری
پروتکل OpenID Connect برای احراز هویت کاربران و درخواست منابعی از جمله توکنها، اطلاعات کاربر و کلیدهای عمومی، نیاز به استفاده از چندین نقطه پایانی دارد.
To simplify implementations and increase flexibility, OpenID Connect allows the use of a "Discovery document," a JSON document found at a well-known location containing key-value pairs which provide details about the OpenID Connect provider's configuration, including the URIs of the authorization, token, revocation, userinfo, and public-keys endpoints. The Discovery document for Google's OpenID Connect service may be retrieved from:
https://accounts.google.com/.well-known/openid-configuration
To use Google's OpenID Connect services, you should hard-code the Discovery-document URI ( https://accounts.google.com/.well-known/openid-configuration
) into your application. Your application fetches the document, applies caching rules in the response, then retrieves endpoint URIs from it as needed. For example, to authenticate a user, your code would retrieve the authorization_endpoint
metadata value ( https://accounts.google.com/o/oauth2/v2/auth
in the example below) as the base URI for authentication requests that are sent to Google.
Here is an example of such a document; the field names are those specified in OpenID Connect Discovery 1.0 (refer to that document for their meanings). The values are purely illustrative and might change, although they are copied from a recent version of the actual Google Discovery document:
{ "issuer": "https://accounts.google.com", "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth", "device_authorization_endpoint": "https://oauth2.googleapis.com/device/code", "token_endpoint": "https://oauth2.googleapis.com/token", "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo", "revocation_endpoint": "https://oauth2.googleapis.com/revoke", "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs", "response_types_supported": [ "code", "token", "id_token", "code token", "code id_token", "token id_token", "code token id_token", "none" ], "subject_types_supported": [ "public" ], "id_token_signing_alg_values_supported": [ "RS256" ], "scopes_supported": [ "openid", "email", "profile" ], "token_endpoint_auth_methods_supported": [ "client_secret_post", "client_secret_basic" ], "claims_supported": [ "aud", "email", "email_verified", "exp", "family_name", "given_name", "iat", "iss", "locale", "name", "picture", "sub" ], "code_challenge_methods_supported": [ "plain", "S256" ] }
You may be able to avoid an HTTP round-trip by caching the values from the Discovery document. Standard HTTP caching headers are used and should be respected.
کتابخانههای کلاینت
The following client libraries make implementing OAuth 2.0 simpler by integrating with popular frameworks:
OpenID Connect compliance
Google's OAuth 2.0 authentication system supports the required features of the OpenID Connect Core specification. Any client which is designed to work with OpenID Connect should interoperate with this service (with the exception of the OpenID Request Object ).