گوگل متعهد به پیشبرد برابری نژادی برای جوامع سیاه پوست است. ببینید چگونه.

OpenID اتصال

نقطه پایانی OpenID Connect Google دارای OpenID مجاز است.

OIuth 2.0 API گوگل می تواند برای تأیید اعتبار و مجوز استفاده شود. این سند نحوه اجرای OAuth 2.0 ما را برای تأیید اعتبار توصیف می کند ، که مطابق با مشخصات OpenID Connect است و دارای مجوز OpenID است . اسنادی که در استفاده از OAuth 2.0 برای دسترسی به API های Google وجود دارد ، در مورد این سرویس نیز صدق می کند. اگر می خواهید این پروتکل را به صورت تعاملی کاوش کنید ، Google OAuth 2.0 Playground را پیشنهاد می کنیم. برای دریافت راهنمایی در مورد Stack Overflow ، س questionsالات خود را با "google-oauth" برچسب گذاری کنید.

راه اندازی OAuth 2.0

قبل از اینکه برنامه شما بتواند از سیستم احراز هویت OAuth 2.0 گوگل برای ورود کاربر استفاده کند ، باید یک پروژه را در Google API Console تنظیم کنید تا اعتبار OAuth 2.0 را بدست آورید ، URI هدایت را تنظیم کنید و (به صورت اختیاری) اطلاعات مارک تجاری خود را که کاربران در کاربر می بینند ، تنظیم کنید - صفحه رضایت همچنین می توانید از API Console برای ایجاد یک حساب سرویس ، فعال کردن صورتحساب ، تنظیم فیلتر و انجام سایر کارها استفاده کنید. برای جزئیات بیشتر ، به راهنما Google API Console مراجعه کنید .

اعتبار OAuth 2.0 را دریافت کنید

برای احراز هویت کاربران و دسترسی به API های گوگل ، به مدارک OAuth 2.0 از جمله شناسه مشتری و راز مشتری احتیاج دارید.

برای مشاهده شناسه مشتری و راز مشتری برای اعتبار OAuth 2.0 داده شده ، روی متن زیر کلیک کنید: اعتبار را انتخاب کنید . در پنجره ای که باز می شود ، پروژه خود و اعتبار مورد نظر خود را انتخاب کرده و سپس بر روی View کلیک کنید.

یا ، شناسه مشتری و راز مشتری خود را از صفحه اعتبارنامه در API Console :

  1. Go to the Credentials page.
  2. بر روی نام اعتبار خود یا نماد مداد ( ) کلیک . شناسه مشتری و راز شما در بالای صفحه قرار دارند.

URI هدایت را تنظیم کنید

URI هدایتی که در API Console تنظیم کرده اید تعیین می کند که Google پاسخ درخواست های احراز هویت شما را از کجا ارسال می کند .

برای ایجاد ، مشاهده و یا ویرایش URI های تغییر مسیر برای اعتبار OAuth 2.0 داده شده ، موارد زیر را انجام دهید:

  1. Go to the Credentials page.
  2. در بخش شناسه های مشتری OAuth 2.0 از صفحه ، روی اعتبار نامه کلیک کنید.
  3. URI های تغییر مسیر را مشاهده یا ویرایش کنید.

اگر در صفحه شناسنامه ها هیچ بخش شناسه مشتری OAuth 2.0 وجود ندارد ، پروژه شما هیچ اعتبار OAuth ندارد. برای ایجاد یک ، روی ایجاد اعتبارنامه کلیک کنید.

صفحه رضایت کاربر را سفارشی کنید

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

صفحه رضایت کاربر همچنین اطلاعات مربوط به مارک تجاری مانند نام محصول ، آرم و URL صفحه اصلی شما را ارائه می دهد. شما اطلاعات مارک را در API Console کنترل می کنید.

برای فعال کردن صفحه رضایت پروژه خود:

  1. Consent Screen page در Google API Console .
  2. If prompted, select a project, or create a new one.
  3. فرم را پر کنید و روی ذخیره کلیک کنید.

گفتگوی رضایت زیر نشان می دهد که کاربر وقتی ترکیبی از دامنه های OAuth 2.0 و Google Drive در درخواست وجود دارد ، کاربر چه چیزی را می بیند. (این کادر گفتگوی عمومی با استفاده از Google OAuth 2.0 Playground ایجاد شده است ، بنابراین شامل اطلاعات مارک تجاری که در API Console تنظیم می شود نیست.)

تأیید عکس روی صفحه

دسترسی به سرویس

Google و اشخاص ثالث کتابخانه هایی را ارائه می دهند که می توانید برای مراقبت از بسیاری از جزئیات پیاده سازی احراز هویت کاربران و دسترسی به API های Google از آنها استفاده کنید. به عنوان مثال می توان به Google Sign-In و کتابخانه های سرویس گیرنده Google اشاره کرد که برای سیستم عامل های مختلف در دسترس هستند.

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

احراز هویت کاربر

احراز هویت کاربر شامل اخذ رمز شناسه و اعتبارسنجی آن است. شناسه ها یک ویژگی استاندارد OpenID Connect است که برای استفاده در اشتراک ادعاهای هویت در اینترنت طراحی شده است.

روشی که معمولاً برای احراز هویت کاربر و به دست آوردن شناسه ID استفاده می شود ، جریان "سرور" و جریان "ضمنی" نامیده می شود. جریان سرور به سرور پشتی برنامه اجازه می دهد تا هویت شخص را با استفاده از مرورگر یا دستگاه تلفن همراه تأیید کند. جریان ضمنی هنگامی استفاده می شود که یک برنامه سمت مشتری (معمولاً یک برنامه جاوا اسکریپت که در مرورگر اجرا می شود) به جای اینکه از طریق سرور back-end خود نیاز داشته باشد ، مستقیماً به API ها دسترسی پیدا کند.

این سند نحوه انجام جریان سرور را برای احراز هویت کاربر توصیف می کند. جریان ضمنی به دلیل خطرات امنیتی در مدیریت و استفاده از نشانه ها در سمت مشتری ، به طور قابل توجهی پیچیده تر است. اگر شما نیاز به اجرای یک جریان ضمنی دارید ، ما به شدت توصیه می کنیم از Google Sign-In استفاده کنید .

جریان سرور

مطمئن شوید که برنامه خود را در API Console تنظیم کرده اید تا بتواند از این پروتکل ها استفاده کند و کاربران شما را تأیید اعتبار کند. وقتی کاربری می خواهد با Google وارد سیستم شود ، شما باید:

  1. یک رمز حالت ضد جعل ایجاد کنید
  2. درخواست تأیید اعتبار به Google ارسال کنید
  3. رمز حالت ضد جعل را تأیید کنید
  4. code برای دسترسی به رمز ورود و شناسه مبادله code
  5. اطلاعات کاربر را از شناسه شناسه دریافت کنید
  6. احراز هویت کاربر

1. یک رمز حالت ضد جعل ایجاد کنید

شما باید با جلوگیری از حملات درخواست جعل ، از امنیت کاربران خود محافظت کنید. اولین قدم ایجاد یک رمز جلسه منحصر به فرد است که بین برنامه شما و مشتری کاربر حالت دارد. بعداً شما این رمز جلسه منحصر به فرد را با پاسخ احراز هویت ارائه شده توسط سرویس ورود به سیستم Google OAuth مطابقت داده اید تا بررسی کنید کاربر درخواست می کند و نه یک مهاجم مخرب. از این نشانه ها اغلب به عنوان نشانه های جعل درخواست بین سایت ( CSRF ) یاد می شود.

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

کد زیر تولید نشانه های جلسه منحصر به فرد را نشان می دهد.

PHP

برای استفاده از این نمونه باید کتابخانه سرویس گیرنده Google APIs را برای 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
));

جاوا

برای استفاده از این نمونه باید کتابخانه سرویس گیرنده Google APIs را برای جاوا بارگیری کنید.

// 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);

پایتون

برای استفاده از این نمونه باید کتابخانه سرویس گیرنده Google APIs را برای پایتون بارگیری کنید.

# 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))

2. یک درخواست احراز هویت به Google ارسال کنید

مرحله بعدی تشکیل درخواست HTTPS GET با پارامترهای URI مناسب است. به استفاده از HTTPS به جای HTTP در تمام مراحل این فرآیند توجه داشته باشید. ارتباطات HTTP رد می شود. شما باید از URI پایه از بازیابی سند کشف با استفاده از authorization_endpoint ارزش ابرداده. بحث زیر فرض می کند URI پایه https://accounts.google.com/o/oauth2/v2/auth .

برای یک درخواست اساسی ، پارامترهای زیر را مشخص کنید:

  • client_id ، که از API Console Credentials page دریافت می کنید.
  • response_type ، که در یک درخواست اولیه کد اجازه مجوز ، باید code باشد. (بیشتر بخوانید در response_type .)
  • scope ، که در یک درخواست اساسی باید openid email باشد. (بیشتر بخوانید در scope .)
  • redirect_uri باید نقطه پایانی HTTP در سرور شما باشد که پاسخ گوگل را دریافت کند. این مقدار باید دقیقاً با یکی از URI های تغییر مسیر مجاز برای سرویس گیرنده OAuth 2.0 مطابقت داشته باشد ، که در API Console Credentials page پیکربندی کرده اید. اگر این مقدار با URI مجاز مطابقت نداشته باشد ، درخواست با خطای redirect_uri_mismatch شکست می خورد.
  • state باید مقدار رمز جلسه منحصر به فرد ضد جعل و همچنین سایر اطلاعات مورد نیاز برای بازیابی زمینه را هنگام بازگشت کاربر به برنامه شما ، از جمله URL شروع ، دربردارد. (بیشتر بخوانید در state .)
  • nonce یک مقدار تصادفی است که توسط برنامه شما تولید می شود و در صورت وجود محافظت از پخش را امکان پذیر می کند.
  • login_hint می تواند آدرس ایمیل کاربر یا رشته sub باشد که برابر با Google ID کاربر است. اگر login_hint ارائه login_hint و کاربر در حال حاضر به سیستم وارد شده باشد ، صفحه رضایت شامل درخواست تأیید انتشار آدرس ایمیل کاربر در برنامه شما است. (بیشتر بخوانید در login_hint .)
  • از پارامتر hd برای بهینه سازی جریان OpenID Connect برای کاربران یک دامنه خاص G Suite استفاده کنید. (بیشتر بخوانید در 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

اگر برنامه شما اطلاعات جدیدی درباره آنها درخواست می کند ، یا اگر برنامه شما اجازه دسترسی به حساب را که قبلاً تأیید نکرده اند ، باید موافقت کنید.

3. رمز حالت ضد جعل را تأیید کنید

پاسخ به 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 دریافت شده از Google با رمز جلسه ای که در مرحله 1 ایجاد کرده اید مطابقت دارد. این تأیید صحت رفت و برگشت به شما اطمینان می دهد که کاربر ، نه یک اسکریپت مخرب ، درخواست شما را ارائه می دهد.

کد زیر نشانگر نشانه های جلسه ای است که در مرحله 1 ایجاد کرده اید:

PHP

برای استفاده از این نمونه باید کتابخانه سرویس گیرنده Google APIs را برای 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);
}

جاوا

برای استفاده از این نمونه باید کتابخانه سرویس گیرنده Google APIs را برای جاوا بارگیری کنید.

// 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.");
}

پایتون

برای استفاده از این نمونه باید کتابخانه سرویس گیرنده Google APIs را برای پایتون بارگیری کنید.

# 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

4. code دسترسی به رمز دسترسی و شناسه رمز را مبادله code

پاسخ شامل یک پارامتر code ، یک کد مجوز یکبار مصرف است که سرور شما می تواند با یک رمز دسترسی و یک شناسه ID مبادله کند. سرور شما با ارسال درخواست HTTPS POST این تبادل را انجام می دهد. درخواست POST به نقطه پایانی رمز ارسال می شود ، که باید آن را با استفاده از مقدار token_endpoint از سند Discovery بازیابی کنید. بحث زیر فرض می کند که نقطه نهایی https://oauth2.googleapis.com/token . این درخواست باید شامل پارامترهای زیر در متن POST باشد:

زمینه های
code کد مجوز که از درخواست اولیه بازگردانده می شود .
client_id شناسه مشتری که از API Console Credentials page به دست می آورید ، همانطور که در اعتبارنامه OAuth 2.0 شرح داده شده است.
client_secret راز مشتری که از API Console Credentials page بدست آورده اید ، همانطور که در اعتبارنامه های OAuth 2.0 شرح داده شده است.
redirect_uri یک URI ریدایرکت مجاز برای client_id داده شده در client_id مشخص شده است ، همانطور که در تنظیم URI ریدایرکت توضیح داده شده است.
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 نشانه ای که می تواند به Google API ارسال شود.
expires_in طول عمر باقی مانده از رمز دسترسی در چند ثانیه.
id_token JWT حاوی اطلاعات هویتی مربوط به کاربر است که توسط Google به صورت دیجیتالی امضا شده است.
scope محدوده های دسترسی که توسط access_token اعطا می شود به صورت لیستی از رشته های محدود به فضا و حساس به حروف بزرگ بیان می شود.
token_type نوع نشانه برگشتی را مشخص می کند. در این زمان ، این قسمت همیشه دارای ارزش Bearer .
refresh_token (اختیاری)

این قسمت فقط در صورتی موجود است که پارامتر access_type در درخواست احراز هویت به صورت offline تنظیم شده باشد. برای جزئیات ، به Refresh tokens مراجعه کنید.

5- اطلاعات کاربری را از شناسه ID بدست آورید

شناسه ID یک JWT (JSON Web Token) است ، یعنی یک شی JSON رمزگذاری شده با رمز Base64. به طور معمول ، بسیار مهم است که یک شناسه شناسه را قبل از استفاده اعتبار سنجی کنید ، اما از آنجا که مستقیماً با Google از طریق یک کانال HTTPS بدون واسطه در ارتباط هستید و از راز مشتری خود برای تأیید اعتبار خود در Google استفاده می کنید ، می توانید اطمینان داشته باشید دریافت از طرف گوگل ارائه می شود و معتبر است. اگر سرور شما شناسه شناسه را به سایر اجزای برنامه شما منتقل می کند ، بسیار مهم است که سایر اجزای آن رمز را قبل از استفاده اعتبار سنجی کنند.

از آنجا که اکثر کتابخانه های API اعتبار سنجی را با کار رمزگشایی مقادیر رمزگذاری شده در پایگاه 64url و تجزیه JSON در ترکیب می کنند ، به هر حال با دسترسی به ادعاها در شناسه ID ، به احتمال زیاد اعتبار رمز را تایید خواهید کرد.

محموله شناسه شناسه

شناسه شناسه یک شی J 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"
}

نشانه های Google ID ممکن است شامل زمینه های زیر باشد (معروف به ادعا ):

مطالبه ارائه شده شرح
aud همیشه مخاطبی که این رمز شناسه برای آن در نظر گرفته شده است. این باید یکی از شناسه های مشتری OAuth 2.0 برنامه شما باشد.
exp همیشه زمان انقضا در یا بعد از آن شناسه رمز پذیرفته نمی شود. در زمان یونیکس نمایش داده می شود (ثانیه های عدد صحیح).
iat همیشه زمان صدور شناسه. در زمان یونیکس نمایش داده می شود (ثانیه های عدد صحیح).
iss همیشه شناسه صادر کننده برای صادرکننده پاسخ. برای نشانه های Google ID همیشه https://accounts.google.com یا accounts.google.com .
sub همیشه شناسه ای برای کاربر ، بین تمام حساب های Google منحصر به فرد و هرگز استفاده مجدد نمی شود. یک حساب Google می تواند چندین آدرس ایمیل در زمان های مختلف داشته باشد ، اما مقدار sub هرگز تغییر نمی کند. از sub برنامه خود به عنوان کلید شناسایی منحصر به فرد برای کاربر استفاده کنید. حداکثر طول 255 نویسه حساس به حروف کوچک
at_hash دسترسی به هش رمز تأیید اعتبار رمز دسترسی به رمز هویت را فراهم می کند. اگر شناسه ID با مقدار access_token در جریان سرور صادر شود ، این ادعا همیشه درج می شود. این ادعا می تواند به عنوان مکانیزم جایگزین برای محافظت در برابر حملات جعل درخواست متقابل سایت مورد استفاده قرار گیرد ، اما اگر مراحل 1 و 3 را دنبال کنید ، لازم نیست رمز دسترسی را تأیید کنید.
azp client_id ارائه دهنده مجوز مجاز. این ادعا فقط زمانی لازم است که طرف درخواست کننده شناسه با مخاطبان رمز شناسه یکی نباشد. این ممکن است در Google برای برنامه های ترکیبی وجود داشته باشد که در آن یک برنامه وب و برنامه Android دارای OAuth 2.0 client_id اما از همان پروژه API های Google استفاده می کنند.
email آدرس ایمیل کاربر این مقدار ممکن است مختص این کاربر نباشد و برای استفاده به عنوان کلید اصلی مناسب نباشد. فقط در صورتی ارائه می شود که دامنه شما شامل مقدار دامنه email باشد.
email_verified اگر آدرس ایمیل کاربر تأیید شده باشد ، درست است. در غیر این صورت نادرست است.
family_name نام خانوادگی (نام) یا نام خانوادگی کاربر. ممکن است در صورت وجود ادعای name ارائه شود.
given_name نام یا نام اختصاصی کاربر. ممکن است در صورت وجود ادعای name ارائه شود.
hd دامنه میزبان G Suite کاربر. فقط در صورتی ارائه می شود که کاربر به دامنه میزبانی شده تعلق داشته باشد.
locale محلی کاربر که با برچسب زبان BCP 47 نشان داده می شود. ممکن است در صورت وجود ادعای name ارائه شود.
name نام کامل کاربر ، به صورت قابل نمایش ممکن است ارائه شود:
  • دامنه درخواست شامل رشته "نمایه" بود
  • رمز شناسه از تازه سازی رمز بازگردانده می شود

وقتی ادعاهای name وجود دارد ، می توانید از آنها برای به روزرسانی سوابق کاربر برنامه خود استفاده کنید. توجه داشته باشید که این ادعا هرگز تضمین شده نیست.

nonce ارزش nonce ارائه شده توسط برنامه شما در درخواست احراز هویت. باید اطمینان حاصل کنید که حملات تکرار فقط یک بار ارائه شده است.
picture URL عکس پروفایل کاربر. ممکن است ارائه شود:
  • دامنه درخواست شامل رشته "نمایه" بود
  • رمز شناسه از تازه سازی رمز بازگردانده می شود

وقتی ادعاهای picture وجود دارد ، می توانید از آنها برای به روزرسانی سوابق کاربر برنامه خود استفاده کنید. توجه داشته باشید که این ادعا هرگز تضمین شده نیست.

profile URL صفحه پروفایل کاربر. ممکن است ارائه شود:
  • دامنه درخواست شامل رشته "نمایه" بود
  • رمز شناسه از تازه سازی رمز بازگردانده می شود

وقتی ادعاهای profile وجود دارد ، می توانید از آنها برای به روزرسانی سوابق کاربر برنامه خود استفاده کنید. توجه داشته باشید که این ادعا هرگز تضمین شده نیست.

6. احراز هویت کاربر

پس از به دست آوردن اطلاعات کاربر از شناسه شناسه ، باید پایگاه داده کاربر برنامه خود را جستجو کنید. اگر کاربر قبلاً در پایگاه داده شما وجود دارد ، اگر تمام نیازهای ورود به سیستم با پاسخ Google API برآورده شود ، باید یک جلسه برنامه برای آن کاربر شروع کنید.

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

مباحث پیشرفته

بخشهای زیر با جزئیات بیشتر API Google OAuth 2.0 را توصیف می کنند. این اطلاعات برای توسعه دهندگان با نیازهای پیشرفته در مورد احراز هویت و مجوز در نظر گرفته شده است.

دسترسی به سایر API های Google

یکی از مزایای استفاده از OAuth 2.0 برای احراز هویت این است که برنامه شما می تواند همزمان با احراز هویت کاربر ، اجازه استفاده از سایر API های Google را از طرف کاربر (مانند YouTube ، Google Drive ، Calendar یا مخاطبین) دریافت کند. برای انجام این کار ، دامنه های دیگری را که نیاز دارید در درخواست احراز هویت که برای Google ارسال می کنید وارد کنید. به عنوان مثال ، برای افزودن گروه سنی کاربر به درخواست احراز هویت ، یک پارامتر دامنه openid email https://www.googleapis.com/auth/profile.agerange.read تصویب openid email https://www.googleapis.com/auth/profile.agerange.read . از کاربر به طور مناسب در صفحه رضایت درخواست می شود . رمز دستیابی که از Google پس می گیرید به شما امکان می دهد به تمام API های مربوط به دامنه دسترسی مورد درخواست و اعطای آن دسترسی پیدا کنید.

نشانه ها را تازه کنید

در درخواست دسترسی API شما می توانید یک نشانه تازه سازی درخواست کنید که در هنگام تبادل code بازگردانده شود. یک علامت تازه سازی دسترسی مداوم برنامه شما به API های Google را فراهم می کند در حالی که کاربر در برنامه شما حضور ندارد. برای درخواست یک نشانه تازه سازی ، پارامتر access_type به صورت offline در درخواست احراز هویت خود تنظیم کنید.

ملاحظات:

  • مطمئن شوید که نشانه تازه سازی را با خیال راحت و به طور دائمی ذخیره کنید ، زیرا فقط در اولین باری که جریان تبادل کد را انجام می دهید ، می توانید یک نشانه تازه سازی را به دست آورید.
  • تعداد توکن های تازه سازی که صادر می شوند محدودیت هایی دارند: یک محدودیت برای هر مشتری / کاربر و دیگری برای هر کاربر برای همه کاربران. اگر برنامه شما بیش از حد نشانه های تازه سازی درخواست کند ، ممکن است با این محدودیت ها روبرو شود ، در این حالت نشانه های تازه سازی قدیمی کار نمی کنند.

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

شما می توانید کاربران را به دوباره اجازه به برنامه خود را با تنظیم بی درنگ prompt پارامتر به consent خود را درخواست احراز هویت . وقتی prompt=consent در آن گنجانده شود ، هر زمان که برنامه شما مجوز دسترسی به حوزه را درخواست کند ، صفحه رضایت نمایش داده می شود ، حتی اگر همه محدوده ها قبلاً به پروژه Google API شما اعطا شده باشد. به همین دلیل ، فقط در prompt=consent لزوم prompt=consent را درج کنید.

برای اطلاعات بیشتر در مورد پارامتر prompt ، در جدول پارامترهای URI احراز هویت به prompt مراجعه کنید.

پارامترهای URI احراز هویت

در جدول زیر توضیحات کامل تری از پارامترهای پذیرفته شده توسط API احراز هویت OAuth 2.0 Google ارائه شده است.

پارامتر ضروری شرح
client_id (ضروری) رشته شناسه مشتری که از API Console Credentials page به دست می آورید ، همانطور که در اعتبارنامه های Obtain OAuth 2.0 شرح داده شده است.
nonce (ضروری) یک مقدار تصادفی ایجاد شده توسط برنامه شما که محافظت از پخش را امکان پذیر می کند.
response_type (ضروری) اگر مقدار code ، یک جریان کد مجوز اساسی را راه اندازی می کند ، برای به دست آوردن رمزها به POST به نقطه انتهای رمز نیاز دارد. اگر این مقدار token id_token یا id_token token ، یک جریان ضمنی راه اندازی می شود و برای بازیابی نشانه ها از شناسه #fragment بخش URI نیاز به استفاده از JavaScript در URI هدایت است.
redirect_uri (ضروری) محل ارسال پاسخ را تعیین می کند. مقدار این پارامتر باید دقیقاً با یکی از مقادیر تغییر مسیر مجاز که در API Console Credentials page تنظیم کرده اید مطابقت داشته باشد (در صورت وجود طرح HTTP یا HTTPS ، پرونده و "/"
scope (ضروری)

پارامتر دامنه باید با مقدار openid شروع شود و سپس شامل مقدار profile ، مقدار email یا هر دو باشد.

اگر مقدار دامنه profile موجود باشد ، شناسه شناسه ممکن است شامل ادعاهای پیش فرض profile کاربر باشد (اما تضمین نمی شود).

اگر مقدار دامنه email موجود باشد ، شناسه شناسه شامل ادعاهای email و email email_verified .

علاوه بر این دامنه های خاص OpenID ، استدلال دامنه شما می تواند مقادیر دامنه دیگری را نیز شامل شود. تمام مقادیر حوزه باید از هم جدا شوند. به عنوان مثال ، اگر می خواهید از طریق پرونده به Google Drive کاربر دسترسی داشته باشید ، ممکن است پارامتر دامنه شما openid profile email https://www.googleapis.com/auth/drive.file باشد.

برای کسب اطلاعات در مورد دامنه های موجود ، به OAuth 2.0 Scope for Google API یا اسناد مربوط به Google API که می خواهید استفاده کنید ، مراجعه کنید.

state (اختیاری است ، اما اکیداً توصیه می شود)

یک رشته مات که در پروتکل دور می زند. به عنوان مثال ، به عنوان یک پارامتر URI در جریان اصلی و در شناسه #fragment URI در جریان ضمنی #fragment می شود.

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

access_type (اختیاری) مقادیر مجاز offline و online . این اثر در دسترسی آفلاین ثبت شده است . در صورت درخواست رمز دسترسی ، مشتری نماد تازه سازی دریافت نمی کند مگر اینکه مقدار offline مشخص شود.
display (اختیاری) یک مقدار رشته ASCII برای تعیین نحوه نمایش سرور مجوز برای تأیید اعتبار و رضایت صفحات رابط کاربر. مقادیر زیر مشخص شده و توسط سرورهای Google پذیرفته شده اند ، اما تأثیری در رفتار آن ندارند: page ، popup ، touch و wap .
hd (اختیاری)

پارامتر hd (دامنه میزبان) روند ورود به سیستم حسابهای میزبانی شده G Suite را ساده می کند. با قرار دادن دامنه کاربر G Suite (به عنوان مثال mycollege.edu ) ، می توانید نشان دهید که رابط کاربر انتخاب حساب باید برای حساب های موجود در آن دامنه بهینه شود. برای بهینه سازی برای حساب های G Suite به جای فقط یک دامنه ، مقدار ستاره ( * ) را تنظیم کنید: hd=* .

برای کنترل اینکه چه کسی می تواند به برنامه شما دسترسی پیدا کند ، به این بهینه سازی رابط کاربر اعتماد نکنید ، زیرا درخواست های سمت مشتری می توانند اصلاح شوند. مطمئن باشید که به اعتبار که ID برگردانده رمز دارای hd ارزش ادعا که منطبق بر آنچه شما انتظار (به عنوان مثال mycolledge.edu ). برخلاف پارامتر درخواست ، شناسه شناسه شناسه hd در یک رمز امنیتی از Google موجود است ، بنابراین می توان به مقدار مورد اعتماد اعتماد کرد.

include_granted_scopes (اختیاری) اگر این پارامتر با مقدار true ارائه شده true و درخواست مجوز نیز اعطا شود ، مجوز شامل مجوزهای قبلی است که برای این ترکیب کاربر / برنامه برای سایر دامنه ها داده شده است. به مجوز افزایشی مراجعه کنید.

توجه داشته باشید که نمی توانید مجوز افزایشی را با جریان برنامه نصب شده انجام دهید.

login_hint (اختیاری) وقتی برنامه شما بداند کدام کاربر در تلاش است تا احراز هویت شود ، می تواند این پارامتر را به عنوان راهنمایی برای سرور احراز هویت ارائه دهد. تصویب این نکته انتخاب کننده حساب را سرکوب می کند و یا جعبه ایمیل موجود در فرم ورود به سیستم را از قبل پر می کند ، یا جلسه مناسب را انتخاب می کند (اگر کاربر از ورود به سیستم چندگانه استفاده می کند) ، که به شما کمک می کند از بروز مشکلاتی در صورت بروزرسانی برنامه خود جلوگیری کنید. حساب کاربری اشتباه وارد می شود این مقدار می تواند یک آدرس ایمیل یا رشته sub باشد که معادل شناسه Google کاربر است.
prompt (اختیاری) لیستی از مقادیر رشته ای که به فاصله مشخص شده است و مشخص می کند آیا سرور مجوز از کاربر درخواست احراز هویت مجدد و تأیید می کند. مقادیر ممکن عبارتند از:
  • none

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

  • consent

    قبل از بازگرداندن اطلاعات به مشتری ، سرور مجوز از کاربر درخواست رضایت می کند.

  • select_account

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

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

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

شما باید تمام شناسه های شناسه را در سرور خود تأیید کنید ، مگر اینکه بدانید که آنها مستقیماً از Google آمده اند. به عنوان مثال ، سرور شما باید رمزهای شناسایی را که از برنامه های مشتری شما دریافت می کند ، معتبر تأیید کند.

موارد زیر شرایط متداولی است که ممکن است نشانه های شناسه را به سرور خود ارسال کنید:

  • ارسال نشانه های شناسه با درخواست هایی که باید احراز هویت شوند. شناسه های شناسه به شما کاربر خاصی را می دهند که درخواست کرده و این شناسه برای کدام مشتری داده شده است.

رمزهای شناسایی حساس هستند و در صورت رهگیری می توان از آنها استفاده نادرست کرد. شما باید اطمینان حاصل کنید که این نشانه ها فقط با انتقال آنها از طریق HTTPS و فقط از طریق داده های POST یا در سرصفحه های درخواست به طور ایمن اداره می شوند. اگر شناسه های شناسه را در سرور خود ذخیره می کنید ، باید آنها را نیز به صورت ایمن ذخیره کنید.

یکی از مواردی که رمزهای شناسه را مفید می کند این واقعیت است که می توانید آنها را به اجزای مختلف برنامه خود منتقل کنید. این م componentsلفه ها می توانند از رمز شناسه به عنوان سازوکار احراز هویت سبک برای تأیید اعتبار برنامه و کاربر استفاده کنند. اما قبل از اینکه بتوانید از اطلاعات موجود در شناسه ID استفاده کنید یا به عنوان ادعایی که کاربر تأیید کرده است ، به آن اعتماد کنید ، باید آن را تأیید کنید.

اعتبار سنجی شناسه ID به مراحل مختلفی نیاز دارد:

  1. تأیید کنید که شناسه به درستی توسط صادر کننده امضا شده است. نشانه های صادر شده توسط Google با استفاده از یکی از گواهینامه های موجود در URI مشخص شده در مقدار متاداده jwks_uri سند Discovery امضا می شوند.
  2. بررسی کنید که مقدار ادعای iss در شناسه ID برابر با https://accounts.google.com یا accounts.google.com باشد.
  3. بررسی کنید که مقدار ادعای aud در شناسه ID برابر با شناسه مشتری برنامه شما باشد.
  4. تأیید کنید که زمان انقضا (ادعای exp ) رمز شناسه سپری نشده است.
  5. اگر مقدار پارامتر hd را در درخواست تعیین کرده اید ، بررسی کنید که شناسه ID دارای ادعای hd باشد که با دامنه پذیرفته شده میزبان G Suite مطابقت داشته باشد.

مراحل 2 تا 5 فقط شامل مقایسه رشته و تاریخ است که کاملاً ساده هستند ، بنابراین ما در اینجا جزئیات آنها را توضیح نمی دهیم.

مرحله اول پیچیده تر است و شامل بررسی امضای رمزنگاری است. برای اهداف رفع اشکال ، می توانید از نقطه پایانی tokeninfo Google برای مقایسه با پردازش محلی اجرا شده در سرور یا دستگاه خود استفاده کنید. فرض کنید مقدار شناسه ID شما XYZ123 باشد. سپس می توانید از URI https://oauth2.googleapis.com/tokeninfo?id_token= XYZ123 . اگر امضای توکن معتبر باشد ، پاسخ می تواند محموله JWT به شکل جسم رمزگشایی شده JSON باشد.

نقطه پایانی tokeninfo برای رفع اشکال مفید است اما برای اهداف تولید ، کلیدهای عمومی Google را از نقطه پایانی کلیدها بازیابی کنید و اعتبار سنجی را به صورت محلی انجام دهید. باید URI کلیدها را با استفاده از مقدار فراداده jwks_uri از سند Discovery بازیابی کنید. درخواست های مربوط به نقطه پایانی اشکال زدایی ممکن است تحت فشار قرار بگیرند یا در غیر این صورت خطاهای متناوب داشته باشند.

از آنجا که گوگل کلیدهای عمومی خود را به ندرت تغییر می دهد ، می توانید آنها را با استفاده از دستورالعمل های حافظه پنهان پاسخ HTTP ذخیره کرده و در اکثر موارد ، اعتبارسنجی محلی را بسیار کارآمدتر از استفاده از نقطه پایانی tokeninfo . این اعتبار سنجی نیاز به بازیابی و تجزیه گواهی ها و برقراری تماس های رمزنگاری مناسب برای بررسی امضا دارد. خوشبختانه ، برای تحقق این امر ، کتابخانه های بسیار اشکال زدایی در زبانهای مختلف وجود دارد (نگاه کنید به jwt.io ).

به دست آوردن اطلاعات پروفایل کاربر

برای به دست آوردن اطلاعات نمایه اضافی در مورد کاربر ، می توانید از رمز دسترسی (که برنامه شما در جریان تأیید اعتبار دریافت می کند) و استاندارد OpenID Connect استفاده کنید:

  1. برای سازگاری با OpenID ، باید مقادیر دامنه openid profile را در درخواست احراز هویت خود وارد کنید.

    اگر می خواهید آدرس ایمیل کاربر درج شود ، می توانید مقدار دامنه اضافی email . برای تعیین profile و email ، می توانید پارامتر زیر را در URI درخواست احراز هویت خود قرار دهید:

    scope=openid%20profile%20email
  2. رمز دسترسی خود را به سرصفحه مجوز اضافه کنید و درخواست HTTPS GET به نقطه پایانی userinfo ارسال کنید ، که باید آن را با استفاده از مقدار فراداده userinfo_endpoint از سند Discovery بازیابی کنید. پاسخ userinfo شامل اطلاعات در مورد کاربر، همان طور که در OpenID Connect Standard Claims و claims_supported ارزش ابرداده از سند کشف. کاربران یا سازمان های آنها ممکن است زمینه های خاصی را تأمین یا خودداری کنند ، بنابراین ممکن است برای حوزه های دسترسی مجاز اطلاعاتی برای هر زمینه دریافت نکنید.

سند کشف

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

برای ساده سازی پیاده سازی ها و افزایش انعطاف پذیری ، OpenID Connect اجازه می دهد تا از یک "سند Discovery" استفاده کنید ، یک سند JSON که در یک مکان شناخته شده حاوی جفت مقدار کلید است و جزئیات مربوط به پیکربندی ارائه دهنده OpenID Connect ، از جمله URI های مجاز را فراهم می کند. ، رمز ، لغو ، userinfo ، و نقاط پایانی با کلیدهای عمومی. سند Discovery برای سرویس OpenID Connect گوگل از این بازیابی می شود:

https://accounts.google.com/.well-known/openid-configuration

برای استفاده از سرویس های OpenID Connect گوگل ، باید URI ( https://accounts.google.com/.well-known/openid-configuration ) Discovery-document را در برنامه خود سخت رمزگذاری کنید. برنامه شما سند را واکشی می کند ، قوانین caching را در پاسخ اعمال می کند ، سپس URI های نقطه پایانی را در صورت لزوم از آن بازیابی می کند. به عنوان مثال، در احراز هویت کاربر، کد خود را بازیابی authorization_endpoint ارزش ابرداده ( https://accounts.google.com/o/oauth2/v2/auth در مثال زیر) به عنوان پایه URI برای درخواست احراز هویت که به ارسال گوگل

در اینجا مثالی از چنین سندی آورده شده است. نام فیلدها همان مواردی است که در OpenID Connect Discovery 1.0 مشخص شده است (برای معنی آنها به آن سند مراجعه کنید). مقادیر کاملاً گویا هستند و ممکن است تغییر کنند ، اگرچه از نسخه اخیر سند واقعی Google Discovery کپی شده اند:

{
  "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"
  ]
}

با ذخیره مقادیر موجود در سند Discovery ، می توانید از یک دور برگشت HTTP جلوگیری کنید. از سرآیند های حافظه پنهان استاندارد HTTP استفاده می شود و باید به آنها احترام گذاشت.

کتابخانه های مشتری

کتابخانه های مشتری زیر با ادغام در چارچوب های محبوب پیاده سازی OAuth 2.0 را ساده تر می کنند:

انطباق OpenID Connect

سیستم احراز هویت OAuth 2.0 گوگل از ویژگی های مورد نیاز مشخصات OpenID Connect Core پشتیبانی می کند . هر کلاینتی که برای کار با OpenID Connect طراحی شده است باید با این سرویس ارتباط برقرار کند (به استثنای OpenID Request Object ).