پیوند حساب Google با OAuth

حساب‌ها با استفاده از استاندارد صنعتی OAuth 2.0 ضمنی و جریان‌های کد مجوز مرتبط هستند. سرویس شما باید از مجوز سازگار با OAuth 2.0 و نقاط پایانی تبادل رمز پشتیبانی کند.

在隐式流程中，Google 会在用户的浏览器中打开您的授权端点。成功登录后，您将向 Google 返回一个长期访问令牌。现在，此访问令牌会包含在 Google 发送的每个请求中。

在授权代码流程中，您需要两个端点：

  • 授权端点，用于向尚未登录的用户显示登录界面。授权端点还会创建一个短期授权代码，以记录用户对所请求访问权限的同意情况。

  • 令牌交换端点，负责两种类型的交换：

    1. 使用授权代码换取长期有效的刷新令牌和短期有效的访问令牌。当用户完成账号关联流程时，就会发生此交换。
    2. 将长期有效的刷新令牌换成短期有效的访问令牌。当 Google 需要新的访问令牌（因为现有访问令牌已过期）时，就会发生这种交换。

选择 OAuth 2.0 流程

虽然隐式流程更易于实现，但 Google 建议通过隐式流程签发的访问令牌永不过期。这是因为，在隐式流程中，令牌过期后，系统会强制用户重新关联其账号。如果您出于安全考虑需要令牌过期，我们强烈建议您改用授权码流程。

设计准则

本部分介绍了您为 OAuth 关联流程托管的用户屏幕的设计要求和建议。在 Google 应用调用该 API 后，您的平台会向用户显示登录 Google 页面和账号关联意见征求界面。同意关联账号后，系统会将用户重定向回 Google 的应用。

此图展示了用户将其 Google 账号与您的身份验证系统相关联的步骤。第一个屏幕截图显示了用户从您的平台发起的关联。第二张图片显示用户登录 Google，第三张图片显示用户同意并确认将其 Google 账号与您的应用相关联。最后一张屏幕截图显示 Google 应用中成功关联的用户账号。
图 1.账号关联用户登录 Google 和同意屏幕。

要求

  1. 您必须说明用户的账号将与 Google 相关联，而非 Google Home 或 Google 助理等特定 Google 产品相关联。

建议

建议您执行以下操作：

  1. 显示 Google 的隐私权政策。在同意屏幕上添加指向 Google 隐私权政策的链接。

  2. 要共享的数据。使用清晰简洁的语言告知用户 Google 需要哪些用户数据以及原因。

  3. 添加醒目的号召性用语。在用户同意页面上提供明确的号召性用语，例如“同意并关联”。这是因为用户需要了解他们需要与 Google 分享哪些数据才能关联账号。

  4. 可以取消。为用户提供返回或取消链接的途径，如果用户选择不进行关联。

  5. 明确的登录流程。确保用户有明确的 Google 账号登录方法，例如用户名和密码字段或使用 Google 账号登录。

  6. 能够解除关联。提供一种可让用户解除关联的机制，例如指向您平台上账号设置的网址。或者，您也可以添加指向 Google 账号的链接，以便用户管理其关联的账号。

  7. 能够更改用户账号。建议用户切换账号的方法。如果用户通常拥有多个账号，这种做法尤为有益。

    • 如果用户必须关闭意见征求界面才能切换账号，请向 Google 发送可恢复的错误，以便用户可以使用 OAuth 关联和隐式流程登录所需的账号。

  8. 添加您的徽标。在意见征求页面上显示您的公司徽标。 按照您的样式准则放置徽标。如果您还想显示 Google 的徽标，请参阅徽标和商标。

创建项目

如需创建使用账号关联的项目，请执行以下操作：

  2. 点击 Create project。
  3. 输入名称或接受生成的建议。
  4. 确认或修改所有剩余字段。
  5. 点击创建。

如需查看项目 ID，请执行以下操作：

  2. 在着陆页的表格中找到您的项目。项目 ID 会显示在 ID 列中。

Google 账号关联流程包含一个权限请求页面，该页面会告知用户哪个应用在请求访问其数据、请求访问哪些类型的数据，以及适用的条款。您需要先配置 OAuth 权限请求页面，然后才能生成 Google API 客户端 ID。

  1. 打开 Google API 控制台的 OAuth 同意屏幕页面。
  2. 如果出现提示，请选择您刚刚创建的项目。

  3. 在“OAuth 同意屏幕”页面上，填写表单，然后点击“保存”按钮。

    应用名称：征求用户同意的应用的名称。名称应准确反映您的应用，并与用户在其他位置看到的应用名称保持一致。应用名称将显示在账号关联权限请求界面上。

    应用徽标：权限请求页面上显示的一张图片，用以让用户认出您的应用。徽标会显示在账号关联权限请求页面和账号设置中

    支持电子邮件地址：供用户就其同意问题与您联系。

    Google API 的范围：借助范围，您的应用可以访问用户的非公开 Google 数据。对于 Google 账号关联使用情形，默认范围（电子邮件地址、个人资料、openid）就足够了，您无需添加任何敏感范围。一般来说，最佳做法是在需要访问权限时逐步请求权限范围，而不是提前请求。了解详情。

    已获授权的网域：为了保护您和您的用户，Google 只允许使用 OAuth 进行身份验证的应用使用已获授权的网域。应用的链接必须托管在已获授权的网域上。了解详情。

    应用首页链接：应用的首页。必须托管在已获授权的网域上。

    应用隐私权政策链接：显示在 Google 账号关联意见征求界面上。必须托管在已获授权的网域上。

    应用服务条款链接（可选）：必须托管在已获授权的网域上。

    图 1. 虚构应用 Tunery 的 Google 账号关联意见征求界面

  4. 查看“验证状态”，如果您的应用需要验证，请点击“提交以供验证”按钮，提交应用以供验证。如需了解详情，请参阅 OAuth 验证要求。

سرور OAuth خود را پیاده سازی کنید

برای پشتیبانی از جریان ضمنی OAuth 2.0، سرویس شما یک نقطه پایانی مجوز را توسط HTTPS در دسترس قرار می دهد. این نقطه پایانی مسئول احراز هویت و کسب رضایت از کاربران برای دسترسی به داده ها است. نقطه پایانی مجوز یک رابط کاربری برای ورود به سیستم به کاربرانی که قبلاً وارد سیستم نشده‌اند ارائه می‌کند و رضایت را برای دسترسی درخواستی ثبت می‌کند.

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

یک جلسه جریان ضمنی OAuth 2.0 که توسط Google آغاز شده است دارای جریان زیر است:

  1. Google نقطه پایانی مجوز شما را در مرورگر کاربر باز می کند. اگر کاربر قبلاً وارد سیستم نشده باشد، وارد سیستم می‌شود، و به Google اجازه می‌دهد تا با API شما به داده‌های خود دسترسی داشته باشد، اگر قبلاً اجازه نداده باشد.
  2. سرویس شما یک نشانه دسترسی ایجاد می‌کند و آن را به Google برمی‌گرداند. برای انجام این کار، مرورگر کاربر را با نشانه دسترسی پیوست شده به درخواست، به Google هدایت کنید.
  3. Google API های سرویس شما را فراخوانی می کند و رمز دسترسی را با هر درخواست پیوست می کند. سرویس شما تأیید می‌کند که نشانه دسترسی به Google مجوز دسترسی به API را می‌دهد و سپس تماس API را تکمیل می‌کند.

رسیدگی به درخواست های مجوز

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

پارامترهای نقطه پایانی مجوز
client_id شناسه مشتری که به Google اختصاص داده اید.
redirect_uri آدرس اینترنتی که پاسخ این درخواست را به آن ارسال می کنید.
state یک مقدار حسابداری که بدون تغییر در URI تغییر مسیر به Google بازگردانده می شود.
response_type نوع مقداری که باید در پاسخ برگردانده شود. برای جریان ضمنی OAuth 2.0، نوع پاسخ همیشه token است.
user_locale تنظیم زبان حساب Google در قالب RFC5646 برای بومی سازی محتوای شما به زبان دلخواه کاربر استفاده می شود.

به عنوان مثال، اگر نقطه پایانی مجوز شما در https://myservice.example.com/auth موجود باشد، ممکن است یک درخواست به شکل زیر باشد:

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token&user_locale=LOCALE

برای اینکه نقطه پایانی مجوز شما به درخواست‌های ورود به سیستم رسیدگی کند، مراحل زیر را انجام دهید:

  1. برای جلوگیری از اعطای دسترسی به برنامه های مشتری ناخواسته یا پیکربندی نادرست، مقادیر client_id و redirect_uri را تأیید کنید:

    • تأیید کنید که client_id با شناسه مشتری که به Google اختصاص داده اید مطابقت دارد.
    • تأیید کنید که URL مشخص شده توسط پارامتر redirect_uri شکل زیر را دارد: 
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID

  2. بررسی کنید که آیا کاربر به سرویس شما وارد شده است یا خیر. اگر کاربر وارد سیستم نشده است، جریان ورود به سیستم یا ثبت نام سرویس خود را تکمیل کنید.

  3. یک نشانه دسترسی برای Google ایجاد کنید تا از آن برای دسترسی به API شما استفاده کند. نشانه دسترسی می‌تواند هر مقدار رشته‌ای باشد، اما باید به‌طور منحصربه‌فرد نشان‌دهنده کاربر و کلاینتی باشد که نشانه برای آن است و نباید قابل حدس زدن باشد.

  4. یک پاسخ HTTP ارسال کنید که مرورگر کاربر را به URL مشخص شده توسط پارامتر redirect_uri هدایت می کند. تمام پارامترهای زیر را در قطعه URL وارد کنید:

    • access_token : نشانه دسترسی که ایجاد کردید
    • token_type : bearer رشته
    • state : مقدار حالت اصلاح نشده از درخواست اصلی

    مثال زیر نمونه ای از URL به دست آمده است:

    https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

کنترل‌کننده تغییر مسیر OAuth 2.0 Google نشانه دسترسی را دریافت می‌کند و تأیید می‌کند که مقدار state تغییر نکرده است. پس از اینکه Google یک نشانه دسترسی برای سرویس شما به دست آورد، Google این رمز را به تماس های بعدی به API های سرویس شما متصل می کند.

رسیدگی به درخواست های اطلاعات کاربر

نقطه پایانی userinfo یک منبع محافظت شده OAuth 2.0 است که ادعاهای مربوط به کاربر پیوند شده را برمی‌گرداند. پیاده سازی و میزبانی نقطه پایانی اطلاعات کاربر اختیاری است، به جز موارد استفاده زیر:

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

سرصفحه های درخواست نقطه پایانی کاربر
Authorization header نشانه دسترسی از نوع Bearer.

به عنوان مثال، اگر نقطه پایانی اطلاعات کاربری شما در https://myservice.example.com/userinfo در دسترس باشد، ممکن است یک درخواست به شکل زیر باشد:

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

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

  1. رمز دسترسی را از سربرگ Authorization استخراج کنید و اطلاعات کاربر مرتبط با نشانه دسترسی را برگردانید.
  2. اگر رمز دسترسی نامعتبر است، با استفاده از سربرگ پاسخ WWW-Authenticate خطای غیرمجاز HTTP 401 را برگردانید. در زیر نمونه ای از پاسخ خطای userinfo آورده شده است:
    HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",
error_description="The Access Token expired"
    اگر یک پاسخ خطای 401 غیرمجاز یا هر پاسخ خطای ناموفق دیگری در طول فرآیند پیوند داده شود، خطا غیرقابل بازیابی خواهد بود، رمز بازیابی شده کنار گذاشته می شود و کاربر باید دوباره فرآیند پیوند را آغاز کند.

  3. اگر نشانه دسترسی معتبر است، پاسخ HTTP 200 را با شی JSON زیر در بدنه پاسخ HTTPS برگردانید:

    {
"sub": "USER_UUID",
"email": "EMAIL_ADDRESS",
"given_name": "FIRST_NAME",
"family_name": "LAST_NAME",
"name": "FULL_NAME",
"picture": "PROFILE_PICTURE",
}
     اگر نقطه پایانی اطلاعات کاربری شما یک پاسخ موفقیت آمیز HTTP 200 برگرداند، رمز بازیابی شده و ادعاها در برابر حساب Google کاربر ثبت می شود.

    پاسخ نقطه پایانی اطلاعات کاربر
    sub یک شناسه منحصر به فرد که کاربر را در سیستم شما شناسایی می کند.
    email آدرس ایمیل کاربر.
    given_name اختیاری: نام کاربر.
    family_name اختیاری: نام خانوادگی کاربر.
    name اختیاری: نام کامل کاربر.
    picture اختیاری: تصویر نمایه کاربر.

اعتبار بخشیدن به اجرای شما

می‌توانید اجرای خود را با استفاده از ابزار OAuth 2.0 Playground تأیید کنید.

در ابزار، مراحل زیر را انجام دهید:

  1. روی پیکربندی کلیک کنید تا پنجره OAuth 2.0 Configuration باز شود.
  2. در قسمت جریان OAuth ، سمت مشتری را انتخاب کنید.
  3. در قسمت OAuth Endpoints ، سفارشی را انتخاب کنید.
  4. نقطه پایانی OAuth 2.0 و شناسه مشتری که به Google اختصاص داده اید را در فیلدهای مربوطه مشخص کنید.
  5. در بخش Step 1 ، هیچ حوزه Google را انتخاب نکنید. در عوض، این فیلد را خالی بگذارید یا یک محدوده معتبر برای سرور خود تایپ کنید (یا یک رشته دلخواه اگر از دامنه های OAuth استفاده نمی کنید). وقتی کارتان تمام شد، روی Authorize APIs کلیک کنید.
  6. در بخش‌های Step 2 و Step 3 ، جریان OAuth 2.0 را طی کنید و بررسی کنید که هر مرحله طبق برنامه کار می‌کند.

می‌توانید اجرای خود را با استفاده از ابزار نمایشی پیوند حساب Google تأیید کنید.

در ابزار، مراحل زیر را انجام دهید:

  1. روی دکمه Sign-in with Google کلیک کنید.
  2. حسابی را که می‌خواهید پیوند دهید انتخاب کنید.
  3. شناسه سرویس را وارد کنید.
  4. به صورت اختیاری یک یا چند محدوده را وارد کنید که درخواست دسترسی به آنها را دارید.
  5. روی Start Demo کلیک کنید.
  6. هنگامی که از شما خواسته شد، تأیید کنید که ممکن است با درخواست پیوند موافقت کنید و آن را رد کنید.
  7. تأیید کنید که به پلتفرم خود هدایت شده اید.
،

حساب‌ها با استفاده از استاندارد صنعتی OAuth 2.0 ضمنی و جریان‌های کد مجوز مرتبط هستند. سرویس شما باید از مجوز سازگار با OAuth 2.0 و نقاط پایانی تبادل رمز پشتیبانی کند.

在隐式流程中，Google 会在用户的浏览器中打开您的授权端点。成功登录后，您将向 Google 返回一个长期访问令牌。现在，此访问令牌会包含在 Google 发送的每个请求中。

在授权代码流程中，您需要两个端点：

  • 授权端点，用于向尚未登录的用户显示登录界面。授权端点还会创建一个短期授权代码，以记录用户对所请求访问权限的同意情况。

  • 令牌交换端点，负责两种类型的交换：

    1. 使用授权代码换取长期有效的刷新令牌和短期有效的访问令牌。当用户完成账号关联流程时，就会发生此交换。
    2. 将长期有效的刷新令牌换成短期有效的访问令牌。当 Google 需要新的访问令牌（因为现有访问令牌已过期）时，就会发生这种交换。

选择 OAuth 2.0 流程

虽然隐式流程更易于实现，但 Google 建议通过隐式流程签发的访问令牌永不过期。这是因为，在隐式流程中，令牌过期后，系统会强制用户重新关联其账号。如果您出于安全考虑需要令牌过期，我们强烈建议您改用授权码流程。

设计准则

本部分介绍了您为 OAuth 关联流程托管的用户屏幕的设计要求和建议。在 Google 应用调用该 API 后，您的平台会向用户显示登录 Google 页面和账号关联意见征求界面。同意关联账号后，系统会将用户重定向回 Google 的应用。

此图展示了用户将其 Google 账号与您的身份验证系统相关联的步骤。第一个屏幕截图显示了用户从您的平台发起的关联。第二张图片显示用户登录 Google，第三张图片显示用户同意并确认将其 Google 账号与您的应用相关联。最后一张屏幕截图显示 Google 应用中成功关联的用户账号。
图 1.账号关联用户登录 Google 和同意屏幕。

要求

  1. 您必须说明用户的账号将与 Google 相关联，而非 Google Home 或 Google 助理等特定 Google 产品相关联。

建议

建议您执行以下操作：

  1. 显示 Google 的隐私权政策。在同意屏幕上添加指向 Google 隐私权政策的链接。

  2. 要共享的数据。使用清晰简洁的语言告知用户 Google 需要哪些用户数据以及原因。

  3. 添加醒目的号召性用语。在用户同意页面上提供明确的号召性用语，例如“同意并关联”。这是因为用户需要了解他们需要与 Google 分享哪些数据才能关联账号。

  4. 可以取消。为用户提供返回或取消链接的途径，如果用户选择不进行关联。

  5. 明确的登录流程。确保用户有明确的 Google 账号登录方法，例如用户名和密码字段或使用 Google 账号登录。

  6. 能够解除关联。提供一种可让用户解除关联的机制，例如指向您平台上账号设置的网址。或者，您也可以添加指向 Google 账号的链接，以便用户管理其关联的账号。

  7. 能够更改用户账号。建议用户切换账号的方法。如果用户通常拥有多个账号，这种做法尤为有益。

    • 如果用户必须关闭意见征求界面才能切换账号，请向 Google 发送可恢复的错误，以便用户可以使用 OAuth 关联和隐式流程登录所需的账号。

  8. 添加您的徽标。在意见征求页面上显示您的公司徽标。 按照您的样式准则放置徽标。如果您还想显示 Google 的徽标，请参阅徽标和商标。

创建项目

如需创建使用账号关联的项目，请执行以下操作：

  2. 点击 Create project。
  3. 输入名称或接受生成的建议。
  4. 确认或修改所有剩余字段。
  5. 点击创建。

如需查看项目 ID，请执行以下操作：

  2. 在着陆页的表格中找到您的项目。项目 ID 会显示在 ID 列中。

Google 账号关联流程包含一个权限请求页面，该页面会告知用户哪个应用在请求访问其数据、请求访问哪些类型的数据，以及适用的条款。您需要先配置 OAuth 权限请求页面，然后才能生成 Google API 客户端 ID。

  1. 打开 Google API 控制台的 OAuth 同意屏幕页面。
  2. 如果出现提示，请选择您刚刚创建的项目。

  3. 在“OAuth 同意屏幕”页面上，填写表单，然后点击“保存”按钮。

    应用名称：征求用户同意的应用的名称。名称应准确反映您的应用，并与用户在其他位置看到的应用名称保持一致。应用名称将显示在账号关联权限请求界面上。

    应用徽标：权限请求页面上显示的一张图片，用以让用户认出您的应用。徽标会显示在账号关联权限请求页面和账号设置中

    支持电子邮件地址：供用户就其同意问题与您联系。

    Google API 的范围：借助范围，您的应用可以访问用户的非公开 Google 数据。对于 Google 账号关联使用情形，默认范围（电子邮件地址、个人资料、openid）就足够了，您无需添加任何敏感范围。一般来说，最佳做法是在需要访问权限时逐步请求权限范围，而不是提前请求。了解详情。

    已获授权的网域：为了保护您和您的用户，Google 只允许使用 OAuth 进行身份验证的应用使用已获授权的网域。应用的链接必须托管在已获授权的网域上。了解详情。

    应用首页链接：应用的首页。必须托管在已获授权的网域上。

    应用隐私权政策链接：显示在 Google 账号关联意见征求界面上。必须托管在已获授权的网域上。

    应用服务条款链接（可选）：必须托管在已获授权的网域上。

    图 1. 虚构应用 Tunery 的 Google 账号关联意见征求界面

  4. 查看“验证状态”，如果您的应用需要验证，请点击“提交以供验证”按钮，提交应用以供验证。如需了解详情，请参阅 OAuth 验证要求。

سرور OAuth خود را پیاده سازی کنید

برای پشتیبانی از جریان ضمنی OAuth 2.0، سرویس شما یک نقطه پایانی مجوز را توسط HTTPS در دسترس قرار می دهد. این نقطه پایانی مسئول احراز هویت و کسب رضایت از کاربران برای دسترسی به داده ها است. نقطه پایانی مجوز یک رابط کاربری برای ورود به سیستم به کاربرانی که قبلاً وارد سیستم نشده‌اند ارائه می‌کند و رضایت را برای دسترسی درخواستی ثبت می‌کند.

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

یک جلسه جریان ضمنی OAuth 2.0 که توسط Google آغاز شده است دارای جریان زیر است:

  1. Google نقطه پایانی مجوز شما را در مرورگر کاربر باز می کند. اگر کاربر قبلاً وارد سیستم نشده باشد، وارد سیستم می‌شود، و به Google اجازه می‌دهد تا با API شما به داده‌های خود دسترسی داشته باشد، اگر قبلاً اجازه نداده باشد.
  2. سرویس شما یک نشانه دسترسی ایجاد می‌کند و آن را به Google برمی‌گرداند. برای انجام این کار، مرورگر کاربر را با نشانه دسترسی پیوست شده به درخواست، به Google هدایت کنید.
  3. Google API های سرویس شما را فراخوانی می کند و رمز دسترسی را با هر درخواست پیوست می کند. سرویس شما تأیید می‌کند که نشانه دسترسی به Google مجوز دسترسی به API را می‌دهد و سپس تماس API را تکمیل می‌کند.

رسیدگی به درخواست های مجوز

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

پارامترهای نقطه پایانی مجوز
client_id شناسه مشتری که به Google اختصاص داده اید.
redirect_uri آدرس اینترنتی که پاسخ این درخواست را به آن ارسال می کنید.
state یک مقدار حسابداری که بدون تغییر در URI تغییر مسیر به Google بازگردانده می شود.
response_type نوع مقداری که باید در پاسخ برگردانده شود. برای جریان ضمنی OAuth 2.0، نوع پاسخ همیشه token است.
user_locale تنظیم زبان حساب Google در قالب RFC5646 برای بومی سازی محتوای شما به زبان دلخواه کاربر استفاده می شود.

به عنوان مثال، اگر نقطه پایانی مجوز شما در https://myservice.example.com/auth موجود باشد، ممکن است یک درخواست به شکل زیر باشد:

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&response_type=token&user_locale=LOCALE

برای اینکه نقطه پایانی مجوز شما به درخواست‌های ورود به سیستم رسیدگی کند، مراحل زیر را انجام دهید:

  1. برای جلوگیری از اعطای دسترسی به برنامه های مشتری ناخواسته یا پیکربندی نادرست، مقادیر client_id و redirect_uri را تأیید کنید:

    • تأیید کنید که client_id با شناسه مشتری که به Google اختصاص داده اید مطابقت دارد.
    • تأیید کنید که URL مشخص شده توسط پارامتر redirect_uri شکل زیر را دارد: 
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID

  2. بررسی کنید که آیا کاربر به سرویس شما وارد شده است یا خیر. اگر کاربر وارد سیستم نشده است، جریان ورود به سیستم یا ثبت نام سرویس خود را تکمیل کنید.

  3. یک نشانه دسترسی برای Google ایجاد کنید تا از آن برای دسترسی به API شما استفاده کند. نشانه دسترسی می‌تواند هر مقدار رشته‌ای باشد، اما باید به‌طور منحصربه‌فرد نشان‌دهنده کاربر و کلاینتی باشد که نشانه برای آن است و نباید قابل حدس زدن باشد.

  4. یک پاسخ HTTP ارسال کنید که مرورگر کاربر را به URL مشخص شده توسط پارامتر redirect_uri هدایت می کند. تمام پارامترهای زیر را در قطعه URL وارد کنید:

    • access_token : نشانه دسترسی که ایجاد کردید
    • token_type : bearer رشته
    • state : مقدار حالت اصلاح نشده از درخواست اصلی

    مثال زیر نمونه ای از URL به دست آمده است:

    https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

کنترل‌کننده تغییر مسیر OAuth 2.0 Google نشانه دسترسی را دریافت می‌کند و تأیید می‌کند که مقدار state تغییر نکرده است. پس از اینکه Google یک نشانه دسترسی برای سرویس شما به دست آورد، Google این رمز را به تماس های بعدی به API های سرویس شما متصل می کند.

رسیدگی به درخواست های اطلاعات کاربر

نقطه پایانی userinfo یک منبع محافظت شده OAuth 2.0 است که ادعاهای مربوط به کاربر پیوند شده را برمی‌گرداند. پیاده سازی و میزبانی نقطه پایانی اطلاعات کاربر اختیاری است، به جز موارد استفاده زیر:

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

سرصفحه های درخواست نقطه پایانی کاربر
Authorization header نشانه دسترسی از نوع Bearer.

به عنوان مثال، اگر نقطه پایانی اطلاعات کاربری شما در https://myservice.example.com/userinfo در دسترس باشد، ممکن است یک درخواست به شکل زیر باشد:

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

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

  1. رمز دسترسی را از سربرگ Authorization استخراج کنید و اطلاعات کاربر مرتبط با نشانه دسترسی را برگردانید.
  2. اگر رمز دسترسی نامعتبر است، با استفاده از سربرگ پاسخ WWW-Authenticate خطای غیرمجاز HTTP 401 را برگردانید. در زیر نمونه ای از پاسخ خطای userinfo آورده شده است:
    HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",
error_description="The Access Token expired"
    اگر یک پاسخ خطای 401 غیرمجاز یا هر پاسخ خطای ناموفق دیگری در طول فرآیند پیوند داده شود، خطا غیرقابل بازیابی خواهد بود، رمز بازیابی شده کنار گذاشته می شود و کاربر باید دوباره فرآیند پیوند را آغاز کند.

  3. اگر نشانه دسترسی معتبر است، پاسخ HTTP 200 را با شی JSON زیر در بدنه پاسخ HTTPS برگردانید:

    {
"sub": "USER_UUID",
"email": "EMAIL_ADDRESS",
"given_name": "FIRST_NAME",
"family_name": "LAST_NAME",
"name": "FULL_NAME",
"picture": "PROFILE_PICTURE",
}
     اگر نقطه پایانی اطلاعات کاربری شما یک پاسخ موفقیت آمیز HTTP 200 برگرداند، رمز بازیابی شده و ادعاها در برابر حساب Google کاربر ثبت می شود.

    پاسخ نقطه پایانی اطلاعات کاربر
    sub یک شناسه منحصر به فرد که کاربر را در سیستم شما شناسایی می کند.
    email آدرس ایمیل کاربر.
    given_name اختیاری: نام کاربر.
    family_name اختیاری: نام خانوادگی کاربر.
    name اختیاری: نام کامل کاربر.
    picture اختیاری: تصویر نمایه کاربر.

اعتبار بخشیدن به اجرای شما

می‌توانید اجرای خود را با استفاده از ابزار OAuth 2.0 Playground تأیید کنید.

در ابزار، مراحل زیر را انجام دهید:

  1. روی پیکربندی کلیک کنید تا پنجره OAuth 2.0 Configuration باز شود.
  2. در قسمت جریان OAuth ، سمت مشتری را انتخاب کنید.
  3. در قسمت OAuth Endpoints ، سفارشی را انتخاب کنید.
  4. نقطه پایانی OAuth 2.0 و شناسه مشتری که به Google اختصاص داده اید را در فیلدهای مربوطه مشخص کنید.
  5. در بخش Step 1 ، هیچ حوزه Google را انتخاب نکنید. در عوض، این فیلد را خالی بگذارید یا یک محدوده معتبر برای سرور خود تایپ کنید (یا یک رشته دلخواه اگر از دامنه های OAuth استفاده نمی کنید). وقتی کارتان تمام شد، روی Authorize APIs کلیک کنید.
  6. در بخش‌های Step 2 و Step 3 ، جریان OAuth 2.0 را طی کنید و بررسی کنید که هر مرحله طبق برنامه کار می‌کند.

می‌توانید اجرای خود را با استفاده از ابزار نمایشی پیوند حساب Google تأیید کنید.

در ابزار، مراحل زیر را انجام دهید:

  1. روی دکمه Sign-in with Google کلیک کنید.
  2. حسابی را که می‌خواهید پیوند دهید انتخاب کنید.
  3. شناسه سرویس را وارد کنید.
  4. به صورت اختیاری یک یا چند محدوده را وارد کنید که درخواست دسترسی به آنها را دارید.
  5. روی Start Demo کلیک کنید.
  6. هنگامی که از شما خواسته شد، تأیید کنید که ممکن است با درخواست پیوند موافقت کنید و آن را رد کنید.
  7. تأیید کنید که به پلتفرم خود هدایت شده اید.