اتصال OpenID

APIهای OAuth 2.0 Google را می توان هم برای احراز هویت و هم برای مجوز استفاده کرد. این سند پیاده‌سازی OAuth 2.0 ما را برای احراز هویت توصیف می‌کند که با مشخصات OpenID Connect مطابقت دارد و دارای گواهی OpenID است. اسناد موجود در استفاده از OAuth 2.0 برای دسترسی به APIهای Google در این سرویس نیز اعمال می شود. اگر می‌خواهید این پروتکل را به صورت تعاملی کاوش کنید، Google OAuth 2.0 Playground را توصیه می‌کنیم. برای دریافت راهنمایی در مورد Stack Overflow ، سؤالات خود را با «google-oauth» تگ کنید.

راه اندازی OAuth 2.0

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

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

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

یک URI تغییر مسیر را تنظیم کنید

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

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

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

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

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

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

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

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

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

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

متداول‌ترین روش‌های مورد استفاده برای احراز هویت یک کاربر و به‌دست آوردن یک شناسه رمز، جریان «سرور» و جریان «ضمنی» نامیده می‌شوند. جریان سرور به سرور پشتیبان یک برنامه اجازه می دهد تا هویت شخص را با استفاده از مرورگر یا دستگاه تلفن همراه تأیید کند. جریان ضمنی زمانی استفاده می‌شود که یک برنامه سمت سرویس گیرنده (معمولاً یک برنامه جاوا اسکریپت که در مرورگر اجرا می‌شود) نیاز به دسترسی مستقیم به APIها به جای سرور بک‌اند خود داشته باشد.

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

جریان سرور

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

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

1. یک توکن حالت ضد جعل ایجاد کنید

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

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

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

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

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

# 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 پایه را از سند Discovery با استفاده از مقدار فراداده authorization_endpoint بازیابی کنید. در بحث زیر فرض می‌شود که URI پایه https://accounts.google.com/o/oauth2/v2/auth است.

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

• client_id ، که از آن به دست می آورید .
• response_type که در یک درخواست جریان کد مجوز اولیه باید code باشد. (بیشتر در response_type بخوانید.)
• scope که در یک درخواست اولیه باید openid email باشد. (در scope بیشتر بخوانید.)
• redirect_uri should be the HTTP endpoint on your server that will receive the response from Google. مقدار باید دقیقاً با یکی از URIهای مجاز تغییر مسیر برای مشتری OAuth 2.0 مطابقت داشته باشد که در آن پیکربندی کرده اید. . اگر این مقدار با یک 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

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

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

پاسخ به redirect_uri که در درخواست مشخص کرده اید ارسال می شود. تمام پاسخ ها در رشته query برگردانده می شوند، همانطور که در زیر نشان داده شده است:

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 ایجاد کرده اید:

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

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

# 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 ، یک کد مجوز یک بار مصرف است که سرور شما می تواند با یک نشانه دسترسی و شناسه مبادله کند. سرور شما این تبادل را با ارسال یک درخواست HTTPS POST انجام می دهد. درخواست POST به نقطه پایانی نشانه ارسال می شود که باید آن را از سند Discovery با استفاده از مقدار فراداده token_endpoint بازیابی کنید. بحث زیر فرض می‌کند که نقطه پایانی https://oauth2.googleapis.com/token است. درخواست باید شامل پارامترهای زیر در بدنه POST باشد:

درخواست واقعی ممکن است مانند مثال زیر باشد:

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 است:

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

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

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

محموله یک رمز شناسه

یک نشانه ID یک شی 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 ممکن است حاوی فیلدهای زیر باشند (که به عنوان ادعا شناخته می‌شوند):

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

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

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

موضوعات پیشرفته

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

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

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

بازخوانی نشانه ها

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

ملاحظات:

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

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

درخواست رضایت مجدد

You can prompt the user to re-authorize your app by setting the prompt parameter to consent in your authentication request . وقتی prompt=consent گنجانده شده باشد، هر بار که برنامه شما مجوز دامنه دسترسی را درخواست می‌کند، صفحه رضایت نمایش داده می‌شود، حتی اگر همه دامنه‌ها قبلاً به پروژه Google APIs شما اعطا شده باشد. به همین دلیل، prompt=consent را فقط در صورت لزوم درج کنید.

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

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

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

اعتبار سنجی یک رمز شناسه

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

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

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

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

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

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

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

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

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

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

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

دریافت اطلاعات پروفایل کاربری

To obtain additional profile information about the user, you can use the access token (which your application receives during the authentication flow ) and the OpenID Connect standard:

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

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

   scope=openid%20profile%20email

2. رمز دسترسی خود را به هدر مجوز اضافه کنید و یک درخواست HTTPS GET به نقطه پایانی اطلاعات کاربر ارسال کنید، که باید آن را از سند Discovery با استفاده از مقدار فوق داده userinfo_endpoint بازیابی کنید. پاسخ اطلاعات کاربر شامل اطلاعاتی در مورد کاربر است، همانطور که در OpenID Connect Standard Claims و مقدار ابرداده claims_supported سند Discovery توضیح داده شده است. کاربران یا سازمان‌های آن‌ها ممکن است انتخاب کنند که فیلدهای خاصی را عرضه کنند یا از آن خودداری کنند، بنابراین ممکن است اطلاعاتی برای هر زمینه برای محدوده دسترسی مجاز خود دریافت نکنید.

سند کشف

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

برای ساده‌سازی پیاده‌سازی‌ها و افزایش انعطاف‌پذیری، OpenID Connect اجازه استفاده از «سند کشف» را می‌دهد، یک سند JSON که در یک مکان شناخته‌شده یافت می‌شود که حاوی جفت‌های کلید-مقدار است که جزئیاتی را درباره پیکربندی ارائه‌دهنده OpenID Connect، از جمله URI‌های مجوز ارائه می‌کند. ، نشانه، ابطال، اطلاعات کاربری و نقاط پایانی کلیدهای عمومی. سند Discovery برای سرویس OpenID Connect Google ممکن است از این موارد بازیابی شود:

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

برای استفاده از سرویس‌های OpenID Connect Google، باید URI Discovery-document ( https://accounts.google.com/.well-known/openid-configuration ) را در برنامه خود کدگذاری کنید. برنامه شما سند را واکشی می کند، قوانین کش را در پاسخ اعمال می کند، سپس 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 را ساده تر می کنند:

• Google APIs Client Library برای جاوا
• Google APIs Client Library برای پایتون
• Google APIs Client Library برای دات نت
• Google APIs Client Library برای Ruby
• Google APIs Client Library برای PHP
• کتابخانه OAuth 2.0 برای Google Web Toolkit
• جعبه ابزار Google برای کنترلرهای Mac OAuth 2.0

انطباق با OpenID Connect

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

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

راه اندازی OAuth 2.0

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

دریافت اعتبار OAUTH 2.0

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

URI تغییر مسیر را تنظیم کنید

URI تغییر مسیر که در آن قرار داده اید determines where Google sends responses to your authentication requests .

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

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

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

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

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

Google و اشخاص ثالث کتابخانه هایی را ارائه می دهند که می توانید از آنها برای مراقبت از بسیاری از جزئیات اجرای کاربران تأیید اعتبار و دسترسی به API های Google استفاده کنید. مثالها شامل خدمات هویت Google و کتابخانه های مشتری Google است که برای انواع سیستم عامل ها در دسترس هستند.

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

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

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

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

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

جریان سرور

اطمینان حاصل کنید که برنامه خود را در برای فعال کردن آن در استفاده از این پروتکل ها و تأیید اعتبار کاربران خود. وقتی کاربر سعی می کند با Google وارد سیستم شود ، شما باید:

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

1. یک نشانه حالت ضد فورژاری ایجاد کنید

شما باید با جلوگیری از حملات جعل درخواست ، از امنیت کاربران خود محافظت کنید. اولین قدم ایجاد یک نشانه جلسه منحصر به فرد است که حالت بین برنامه شما و مشتری کاربر را در خود جای داده است. شما بعداً این نشانه جلسه منحصر به فرد را با پاسخ تأیید اعتبار که توسط سرویس ورود به سیستم Google OAuth برگشته است ، مطابقت دهید تا تأیید کنید که کاربر در حال درخواست است و نه یک مهاجم مخرب. These tokens are often referred to as cross-site request forgery ( CSRF ) tokens.

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

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

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

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

# 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 ارسال کنید

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

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

• client_id ، که از آن به دست می آورید .
• response_type ، که در یک درخواست جریان مجوز اصلی باید code باشد. (بیشتر در response_type بخوانید.)
• scope ، که در یک درخواست اساسی باید openid email باشد. (بیشتر در scope بخوانید.)
• redirect_uri باید نقطه پایانی HTTP در سرور شما باشد که پاسخ Google را دریافت می کند. این مقدار دقیقاً باید با یکی از URI های تغییر مسیر مجاز برای مشتری OAUTH 2.0 مطابقت داشته باشد ، که شما در آن پیکربندی کرده اید . اگر این مقدار با URI مجاز مطابقت نداشته باشد ، درخواست با یک خطای redirect_uri_mismatch شکست خواهد خورد.
• state should include the value of the anti-forgery unique session token, as well as any other information needed to recover the context when the user returns to your application, eg, the starting URL. (بیشتر بخوانید در state .)
• nonce یک مقدار تصادفی است که توسط برنامه شما ایجاد می شود که در صورت وجود محافظت مجدد را امکان پذیر می کند.
• login_hint می تواند آدرس ایمیل کاربر یا sub String باشد که معادل شناسه Google کاربر است. اگر یک login_hint ارائه نمی دهید و کاربر در حال حاضر وارد سیستم شده است ، صفحه رضایت شامل درخواست تأیید برای انتشار آدرس ایمیل کاربر به برنامه شما است. (بیشتر در login_hint بخوانید.)
• از پارامتر hd برای بهینه سازی جریان اتصال OpenID برای کاربران یک دامنه خاص مرتبط با یک فضای کاری Google یا سازمان ابری استفاده کنید (در hd بیشتر بخوانید).

در اینجا نمونه ای از URI تأیید صحت Aruthition Connect 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 ایجاد کرده اید:

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

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

# 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 ، یک کد مجوز یک بار است که سرور شما می تواند برای یک نشانه دسترسی و نشانه شناسه مبادله کند. سرور شما با ارسال درخواست POST HTTPS این مبادله را انجام می دهد. درخواست POST به نقطه پایانی توکن ارسال می شود ، که باید با استفاده از مقدار ابرداده token_endpoint از سند Discovery بازیابی کنید. بحث زیر فرض می کند که نقطه پایانی https://oauth2.googleapis.com/token است. درخواست باید پارامترهای زیر را در بدنه POST قرار دهد:

درخواست واقعی ممکن است مانند مثال زیر به نظر برسد:

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 است:

5. اطلاعات کاربر را از ID Token بدست آورید

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

از آنجا که بیشتر کتابخانه های 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"
}

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

6. کاربر را تأیید کنید

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

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

موضوعات پیشرفته

بخش های زیر 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 را منتقل کنید. از کاربر به طور مناسب در صفحه رضایت نامه خواسته می شود. نشانه دسترسی که از Google دریافت می کنید به شما امکان می دهد به تمام API های مربوط به دامنه دسترسی به درخواست شما و اعطا شده دسترسی پیدا کنید.

بازخوانی نشانه ها

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

ملاحظات:

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

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

درخواست مجدد

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

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

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

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

اعتبار سنجی یک نشانه شناسه

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

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

• ارسال نشانه های شناسه با درخواست هایی که باید تأیید شوند. نشانه های شناسه به شما می گویند کاربر خاصی که درخواست را می کند و برای آن مشتری به کدام مشتری اعطا می شود.

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

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

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

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

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

مرحله اول پیچیده تر است و شامل بررسی امضای رمزنگاری است. برای اهداف اشکال زدایی ، می توانید از نقطه پایانی tokeninfo Google استفاده کنید تا در برابر پردازش محلی که در سرور یا دستگاه خود اجرا شده است مقایسه کنید. Suppose your ID token's value is XYZ123 . سپس شما می توانید uri https://oauth2.googleapis.com/tokeninfo?id_token= XYZ123 را تأیید کنید. اگر امضای توکن معتبر باشد ، پاسخ می تواند بار JWT در فرم شیء رمزگشایی شده JSON خود باشد.

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

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

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

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

1. برای آشنایی با OpenID ، باید مقادیر دامنه openid profile را در درخواست تأیید اعتبار خود درج کنید.

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

   scope=openid%20profile%20email

2. نشانه دسترسی خود را به عنوان مجوز اضافه کرده و درخواست HTTPS GET به نقطه پایانی UserInfo دریافت کنید ، که باید با استفاده از مقدار ابرداده userinfo_endpoint از سند Discovery بازیابی کنید. The userinfo response includes information about the user, as described in OpenID Connect Standard Claims and the claims_supported metadata value of the Discovery document. کاربران یا سازمانهای آنها ممکن است زمینه های خاصی را تهیه یا از آن خودداری کنند ، بنابراین ممکن است برای هر زمینه ای برای دسترسی های مجاز خود اطلاعاتی کسب نکنید.

سند کشف

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

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

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

برای استفاده از خدمات OpenID Connect Google ، باید Discovery-Document URI ( https://accounts.google.com/.well-known/openid-configuration ) را به سختی کدگذاری کنید. برنامه شما سند را واکشی می کند ، قوانین ذخیره سازی را در پاسخ اعمال می کند ، سپس در صورت لزوم ، 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 را ساده تر می کنند:

• کتابخانه مشتری Google APIS برای جاوا
• کتابخانه مشتری Google API برای پایتون
• کتابخانه مشتری Google APIS برای .NET
• کتابخانه مشتری Google APIS برای روبی
• کتابخانه مشتری Google APIS برای PHP
• کتابخانه OAUTH 2.0 برای جعبه ابزار وب Google
• جعبه ابزار Google برای کنترل کننده های Mac OAuth 2.0

انطباق OpenID Connect

سیستم احراز هویت OAUTH 2.0 Google از ویژگی های مورد نیاز مشخصات هسته OpenID Connect پشتیبانی می کند. هر مشتری که برای کار با OpenID Connect طراحی شده باشد باید با این سرویس ارتباط برقرار کند (به استثنای شیء درخواست OpenID ).