این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

اتصال OpenID

نقطه پایانی OpenID Connect Google دارای گواهی 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 برای ورود به سیستم استفاده کند، باید پروژه ای را در Google API Console برای دریافت اعتبارنامه OAuth 2.0، یک URI تغییر مسیر تنظیم کنید، و (اختیاری) اطلاعات نام تجاری را که کاربران شما در صفحه رضایت کاربر می بینند سفارشی کنید. شما همچنین می توانید استفاده کنید API Console برای ایجاد یک حساب سرویس، فعال کردن صورتحساب، تنظیم فیلتر کردن، و انجام کارهای دیگر. برای جزئیات بیشتر، نگاه کنید به Google API Consoleکمک کنید .

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

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

要查看给定OAuth 2.0凭据的客户端ID和客户端密钥，请单击以下文本：选择凭据。在打开的窗口中，选择您的项目和所需的凭证，然后单击“ 查看” 。

或者，从API Console的“ 凭据”页面中查看您的客户端ID和客户端密钥：

Go to the Credentials page.
单击您的凭证名称或铅笔（）图标。您的客户ID和密码位于页面顶部。

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

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

要创建，查看或编辑给定OAuth 2.0凭据的重定向URI，请执行以下操作：

Go to the Credentials page.
在页面的OAuth 2.0客户端ID部分中，点击一个凭据。
查看或编辑重定向URI。

如果“凭据”页面上没有OAuth 2.0客户端ID部分，则您的项目没有OAuth凭据。要创建一个，点击创建凭证 。

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

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

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

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

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

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

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

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

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

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

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

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

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

جریان سرور

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

یک نشانه حالت ضد جعل ایجاد کنید
یک درخواست احراز هویت به Google ارسال کنید
رمز حالت ضد جعل را تأیید کنید
تبادل code برای توکن دسترسی و شناسه
اطلاعات کاربر را از توکن ID دریافت کنید
احراز هویت کاربر

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

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

client_id ، که از آن به دست می آورید API ConsoleCredentials page.
response_type که در یک درخواست جریان کد مجوز اولیه باید code باشد. (بیشتر در response_type بخوانید.)
scope که در یک درخواست اولیه باید openid email باشد. (در scope بیشتر بخوانید.)
redirect_uri باید نقطه پایانی HTTP در سرور شما باشد که پاسخ را از Google دریافت می کند. مقدار باید دقیقاً با یکی از URIهای مجاز تغییر مسیر برای مشتری OAuth 2.0 مطابقت داشته باشد که در آن پیکربندی کرده اید. API 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

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

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

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

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

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

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

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 در درخواست احراز هویت خود اضافه کنید.

ملاحظات:

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

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

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

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

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

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

پارامتر	مورد نیاز	توضیحات
`client_id`	(الزامی)	رشته شناسه مشتری که از آن دریافت می کنید API ConsoleCredentials page، همانطور که در دریافت اعتبارنامه OAuth 2.0 توضیح داده شده است.
`nonce`	(الزامی)	یک مقدار تصادفی ایجاد شده توسط برنامه شما که محافظت از پخش مجدد را فعال می کند.
`response_type`	(الزامی)	اگر مقدار `code` باشد، یک جریان کد مجوز پایه راه‌اندازی می‌کند که برای به دست آوردن نشانه‌ها، به یک `POST` به نقطه پایانی نشانه نیاز دارد. اگر مقدار `token id_token` یا `id_token token` باشد، یک جریان ضمنی راه‌اندازی می‌کند که نیاز به استفاده از جاوا اسکریپت در URI تغییر مسیر برای بازیابی نشانه‌ها از شناسه `#fragment` URI دارد.
`redirect_uri`	(الزامی)	محل ارسال پاسخ را مشخص می کند. مقدار این پارامتر باید دقیقاً با یکی از مقادیر تغییر مسیر مجاز که در آن تنظیم کرده اید مطابقت داشته باشد API ConsoleCredentials page (از جمله طرح HTTP یا HTTPS، مورد، و دنباله '/'، در صورت وجود).
`scope`	(الزامی)	پارامتر scope باید با مقدار `openid` شروع شود و سپس شامل مقدار `profile` ، مقدار `email` یا هر دو باشد. اگر مقدار دامنه `profile` وجود داشته باشد، نشانه شناسه ممکن است (اما تضمین نمی شود) ادعاهای `profile` پیش فرض کاربر را شامل شود. اگر مقدار دامنه `email` وجود داشته باشد، رمز شناسه شامل `email` و ادعاهای `email_verified` است. علاوه بر این محدوده های خاص OpenID، آرگومان scope شما می تواند مقادیر دامنه دیگری را نیز شامل شود. همه مقادیر محدوده باید با فاصله از هم جدا شوند. برای مثال، اگر می‌خواهید به ازای هر فایل به Google Drive کاربر دسترسی داشته باشد، پارامتر دامنه شما ممکن است `openid profile email https://www.googleapis.com/auth/drive.file` باشد. برای کسب اطلاعات در مورد دامنه های موجود، به OAuth 2.0 Scopes برای Google API یا اسناد مربوط به Google API که می خواهید استفاده کنید، مراجعه کنید.
`state`	(اختیاری، اما به شدت توصیه می شود)	یک رشته مات که در پروتکل رفت و برگشت می شود. یعنی به عنوان پارامتر URI در جریان پایه و در شناسه `#fragment` #URI در جریان ضمنی برگردانده می شود. `state` می تواند برای ارتباط درخواست ها و پاسخ ها مفید باشد. از آنجا که `redirect_uri` شما قابل حدس زدن است، استفاده از یک مقدار `state` می‌تواند اطمینان شما را از اینکه اتصال ورودی نتیجه درخواست احراز هویت است که توسط برنامه شما آغاز شده است را افزایش دهد. اگر یک رشته تصادفی ایجاد کنید یا هش برخی از وضعیت های سرویس گیرنده (مثلاً یک کوکی) را در این متغیر `state` رمزگذاری کنید، می توانید پاسخ را تأیید اعتبار کنید تا اطمینان حاصل کنید که درخواست و پاسخ از یک مرورگر منشا گرفته اند. این محافظت در برابر حملاتی مانند جعل درخواست بین سایتی را فراهم می کند.
`access_type`	(اختیاری)	مقادیر مجاز `offline` و `online` هستند. این اثر در دسترسی آفلاین مستند شده است. اگر یک نشانه دسترسی درخواست شود، مشتری یک توکن به‌روزرسانی دریافت نمی‌کند مگر اینکه مقدار `offline` مشخص شده باشد.
`display`	(اختیاری)	یک مقدار رشته ASCII برای تعیین اینکه سرور مجوز چگونه صفحات رابط کاربری تایید و رضایت را نمایش می دهد. مقادیر زیر مشخص شده و توسط سرورهای Google پذیرفته شده است، اما هیچ تاثیری بر رفتار آن ندارند: `page` ، `popup` ، `touch` و `wap` .
`hd`	(اختیاری)	فرآیند ورود به حساب های متعلق به یک سازمان Google Cloud را ساده کنید. با اضافه کردن دامنه سازمانی Google Cloud (به عنوان مثال، `mycollege.edu` )، می‌توانید نشان دهید که رابط کاربری انتخاب حساب باید برای حساب‌های موجود در آن دامنه بهینه شود. برای بهینه‌سازی حساب‌های سازمانی Google Cloud به‌جای تنها یک دامنه سازمانی Google Cloud، مقدار یک ستاره ( `` ) را تنظیم کنید: `hd=` . برای کنترل افرادی که می‌توانند به برنامه شما دسترسی داشته باشند، به این بهینه‌سازی UI تکیه نکنید، زیرا درخواست‌های سمت کلاینت قابل تغییر هستند. مطمئن شوید که اعتبار شناسه بازگردانده شده دارای یک مقدار ادعای `hd` است که با آنچه شما انتظار دارید مطابقت دارد (به عنوان مثال `mycolledge.edu` ). برخلاف پارامتر درخواست، ادعای `hd` رمز شناسه در یک نشانه امنیتی از Google وجود دارد، بنابراین می‌توان به مقدار آن اعتماد کرد.
`include_granted_scopes`	(اختیاری)	اگر این پارامتر با مقدار `true` ارائه شود و درخواست مجوز اعطا شود، مجوز شامل هر مجوز قبلی اعطا شده به این ترکیب کاربر/برنامه برای سایر حوزه ها می شود. مجوز افزایشی را ببینید. توجه داشته باشید که نمی توانید مجوز افزایشی را با جریان برنامه نصب شده انجام دهید.
`login_hint`	(اختیاری)	هنگامی که برنامه شما می داند که کدام کاربری را می خواهد احراز هویت کند، می تواند این پارامتر را به عنوان یک اشاره به سرور احراز هویت ارائه دهد. ارسال این راهنمایی، انتخابگر حساب را سرکوب می‌کند و کادر ایمیل را از قبل در فرم ورود به سیستم پر می‌کند، یا جلسه مناسب را انتخاب می‌کند (اگر کاربر از ورود چندگانه استفاده می‌کند)، که می‌تواند به شما کمک کند از مشکلاتی که در برنامه شما رخ می‌دهد جلوگیری کنید. وارد حساب کاربری اشتباه می شود. مقدار می تواند یک آدرس ایمیل یا رشته `sub` باشد که معادل شناسه گوگل کاربر است.
`prompt`	(اختیاری)	فهرستی از مقادیر رشته با فاصله محدود که مشخص می کند آیا سرور مجوز از کاربر برای احراز هویت و رضایت مجدد درخواست می کند یا خیر. مقادیر ممکن عبارتند از: `none` سرور مجوز هیچ صفحه تأیید اعتبار یا رضایت کاربر را نمایش نمی دهد. اگر کاربر قبلاً احراز هویت نشده باشد و رضایت از پیش پیکربندی شده برای دامنه های درخواستی را نداشته باشد، یک خطا را برمی گرداند. می توانید از `none` برای بررسی احراز هویت و/یا رضایت موجود استفاده کنید. `consent` سرور مجوز قبل از بازگرداندن اطلاعات به مشتری، از کاربر درخواست می‌کند که رضایت دهد. `select_account` سرور مجوز از کاربر می خواهد که یک حساب کاربری را انتخاب کند. این به کاربری که چندین حساب در سرور مجوز دارد اجازه می‌دهد تا از میان چندین حسابی که ممکن است جلسات جاری برای آنها داشته باشد، انتخاب کند. اگر مقداری مشخص نشده باشد و کاربر قبلاً مجوز دسترسی نداشته باشد، صفحه رضایت به کاربر نشان داده می شود.

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

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

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

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

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

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

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

بررسی کنید که کد شناسه به درستی توسط صادرکننده امضا شده باشد. توکن‌های صادر شده توسط Google با استفاده از یکی از گواهی‌های موجود در URI مشخص شده در مقدار فراداده jwks_uri سند Discovery امضا می‌شوند.
بررسی کنید که ارزش ادعای iss در کد شناسه برابر با https://accounts.google.com یا accounts.google.com باشد.
بررسی کنید که ارزش ادعای aud در کد ID با شناسه مشتری برنامه شما برابر است.
بررسی کنید که زمان انقضا (ادعای exp ) نشانه شناسه نگذشته باشد.
اگر مقدار پارامتر 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 را ببینید).

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

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

برای سازگاری با OpenID، باید مقادیر محدوده openid profile را در درخواست احراز هویت خود وارد کنید.
اگر می‌خواهید آدرس ایمیل کاربر درج شود، می‌توانید مقدار دامنه اضافی email را مشخص کنید. برای تعیین profile و email ، می توانید پارامتر زیر را در URI درخواست احراز هویت خود وارد کنید:
```
scope=openid%20profile%20email
```
رمز دسترسی خود را به هدر مجوز اضافه کنید و یک درخواست 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 را ساده تر می کنند:

انطباق با OpenID Connect

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

اتصال OpenID

راه اندازی OAuth 2.0

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

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

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

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

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

جریان سرور

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

PHP

جاوا

پایتون

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

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

PHP

جاوا

پایتون

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

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

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

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

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

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

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

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

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

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

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

سند کشف

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

انطباق با OpenID Connect

4. تبادل `code` برای توکن دسترسی و شناسه