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

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

سرویس شما باید از نقاط پایانی احراز هویت و تبادل توکن سازگار با OAuth 2.0 پشتیبانی کند.

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

در جریان کد مجوز ، به دو نقطه پایانی نیاز دارید:

  • نقطه پایانی مجوز ، که رابط کاربری ورود به سیستم را به کاربرانی که هنوز وارد سیستم نشده‌اند، نمایش می‌دهد. نقطه پایانی مجوز همچنین یک کد مجوز کوتاه‌مدت ایجاد می‌کند تا رضایت کاربران برای دسترسی درخواستی را ثبت کند.

  • نقطه پایانی تبادل توکن ، که مسئول دو نوع تبادل است:

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

یک جریان OAuth 2.0 انتخاب کنید

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

دستورالعمل‌های طراحی

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

این شکل مراحل اتصال حساب گوگل کاربر به سیستم احراز هویت شما را نشان می‌دهد. تصویر اول، اتصال آغاز شده توسط کاربر از پلتفرم شما را نشان می‌دهد. تصویر دوم، ورود کاربر به گوگل را نشان می‌دهد، در حالی که تصویر سوم، رضایت و تأیید کاربر برای اتصال حساب گوگل خود به برنامه شما را نشان می‌دهد. تصویر آخر، یک حساب کاربری متصل شده با موفقیت را در برنامه گوگل نشان می‌دهد.
شکل ۱. حساب کاربری که ورود کاربر را به صفحات گوگل و رضایت‌نامه متصل می‌کند.

الزامات

  1. شما باید به کاربر اطلاع دهید که حساب کاربری به گوگل متصل خواهد شد، نه به یک محصول خاص گوگل مانند گوگل هوم یا گوگل اسیستنت.

توصیه‌ها

توصیه می‌کنیم موارد زیر را انجام دهید:

  1. سیاست حفظ حریم خصوصی گوگل را نمایش دهید. پیوندی به سیاست حفظ حریم خصوصی گوگل را در صفحه رضایت‌نامه قرار دهید.

  2. داده‌هایی که باید به اشتراک گذاشته شوند. با زبانی واضح و مختصر به کاربر بگویید که گوگل به چه داده‌هایی از او نیاز دارد و چرا.

  3. فراخوان عمل واضح. در صفحه رضایت خود، یک فراخوان عمل واضح مانند «موافقت و پیوند» بیان کنید. دلیل این امر این است که کاربران باید بدانند برای پیوند دادن حساب‌هایشان، چه داده‌هایی را باید با گوگل به اشتراک بگذارند.

  4. امکان لغو. در صورتی که کاربران تمایلی به لینک دادن نداشته باشند، راهی برای بازگشت یا لغو آن فراهم کنید.

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

  6. امکان لغو پیوند. مکانیزمی برای لغو پیوند کاربران ارائه دهید، مانند URL به تنظیمات حساب کاربری آنها در پلتفرم شما. از طرف دیگر، می‌توانید پیوندی به حساب گوگل قرار دهید که کاربران بتوانند حساب پیوند شده خود را مدیریت کنند.

  7. امکان تغییر حساب کاربری. روشی را برای کاربران پیشنهاد دهید تا حساب(های) خود را تغییر دهند. این امر به ویژه در صورتی مفید است که کاربران تمایل به داشتن چندین حساب داشته باشند.

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

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

پروژه را ایجاد کنید

برای ایجاد پروژه خود با استفاده از پیوند حساب:

  1. به کنسول API گوگل بروید.
  2. روی ایجاد پروژه کلیک کنید.
  3. یک نام وارد کنید یا پیشنهاد تولید شده را بپذیرید.
  4. فیلدهای باقی مانده را تأیید یا ویرایش کنید.
  5. روی ایجاد کلیک کنید.

برای مشاهده شناسه پروژه خود:

  1. به کنسول API گوگل بروید.
  2. پروژه خود را در جدول صفحه اصلی پیدا کنید. شناسه پروژه در ستون شناسه نمایش داده می‌شود.

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

  1. صفحه‌ی رضایت‌نامه‌ی OAuth را در کنسول Google APIs باز کنید.
  2. در صورت درخواست، پروژه‌ای را که تازه ایجاد کرده‌اید انتخاب کنید.

  3. در صفحه «صفحه رضایت OAuth»، فرم را پر کنید و روی دکمه «ذخیره» کلیک کنید.

    نام برنامه: نام برنامه‌ای که درخواست رضایت می‌کند. این نام باید دقیقاً منعکس‌کننده برنامه شما باشد و با نام برنامه‌ای که کاربران در جاهای دیگر می‌بینند، مطابقت داشته باشد. نام برنامه در صفحه رضایت‌نامه پیوند حساب نمایش داده خواهد شد.

    لوگوی برنامه: تصویری در صفحه رضایت‌نامه که به کاربران کمک می‌کند برنامه شما را بشناسند. این لوگو در صفحه رضایت‌نامه پیوند حساب و در تنظیمات حساب نمایش داده می‌شود.

    ایمیل پشتیبانی: برای اینکه کاربران بتوانند در مورد رضایت خود با شما تماس بگیرند.

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

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

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

    پیوند سیاست حفظ حریم خصوصی برنامه: در صفحه رضایت‌نامه پیوند حساب گوگل نشان داده می‌شود. باید در یک دامنه مجاز میزبانی شود.

    لینک شرایط خدمات برنامه (اختیاری): باید روی یک دامنه مجاز میزبانی شود.

    شکل ۱. صفحه رضایت‌نامه اتصال حساب گوگل برای یک برنامه جعلی، Tunery

  4. «وضعیت تأیید» را بررسی کنید، اگر درخواست شما نیاز به تأیید دارد، روی دکمه «ارسال برای تأیید» کلیک کنید تا درخواست شما برای تأیید ارسال شود. برای جزئیات بیشتر به الزامات تأیید OAuth مراجعه کنید.

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

n

To support the OAuth 2.0 implicit flow, your service makes an authorization endpoint available by HTTPS. This endpoint is responsible for authentication and obtaining consent from users for data access. The authorization endpoint presents a sign-in UI to your users that aren't already signed in and records consent to the requested access.

When a Google application needs to call one of your service's authorized APIs, Google uses this endpoint to get permission from your users to call these APIs on their behalf.

Google Account Linking: OAuth Implicit Flow

The following sequence diagram details interactions between the User, Google, and your service's endpoints.

User Google App / Browser Your Auth Endpoint 1. User initiates linking 2. Redirect to Auth Endpoint (GET) client_id, redirect_uri, state, scope 3. Display Sign-in & Consent Screen 4. User Authenticates & Grants Consent 5. Redirect back to Google with Token (GET) access_token, state 6. Store user tokens 7. Access user resources
Figure 1. The sequence of events in the OAuth 2.0 Implicit flow for Google Account Linking.

Roles and responsibilities

The following table defines the roles and responsibilities of actors in the Google Account Linking (GAL) OAuth Implicit flow. Note that in GAL, Google acts as the OAuth Client, while your service acts as the Identity/Service Provider.

Actor / Component GAL Role Responsibilities
Google App / Server OAuth Client Initiates the flow, receives the access token using a browser redirect, and securely stores it to access your service's APIs.
Your Authorization Endpoint Authorization Server Authenticates your users, obtains their consent, and issues long-lived access tokens directly to Google.
Google Redirect URI Callback Endpoint Receives the user redirect from your authorization service with the access_token and state values in the URL fragment.

A typical OAuth 2.0 implicit flow session initiated by Google has the following flow:

  1. Google opens your authorization endpoint in the user's browser. The user signs in, if not signed in already, and grants Google permission to access their data with your API, if they haven't already granted permission.
  2. Your service creates an access token and returns it to Google. To do so, redirect the user's browser back to Google with the access token attached to the request.
  3. Google calls your service's APIs and attaches the access token with each request. Your service verifies that the access token grants Google authorization to access the API and then completes the API call.

Handle authorization requests

When a Google application needs to perform account linking using an OAuth 2.0 implicit flow, Google sends the user to your authorization endpoint with a request that includes the following parameters:

Authorization endpoint parameters
client_id The client ID you assigned to Google.
redirect_uri The URL to which you send the response to this request.
state A bookkeeping value that is passed back to Google unchanged in the redirect URI.
response_type The type of value to return in the response. For the OAuth 2.0 implicit flow, the response type is always token.
user_locale The Google Account language setting in RFC5646 format used to localize your content in the user's preferred language.

For example, if your authorization endpoint is available at https://myservice.example.com/auth, a request might look like the following:

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

For your authorization endpoint to handle sign-in requests, do the following steps:

  1. Verify the client_id and redirect_uri values to prevent granting access to unintended or misconfigured client apps:

    • Confirm that the client_id matches the client ID you assigned to Google.
    • Confirm that the URL specified by the redirect_uri parameter has the following form: 
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID

  2. Check if the user is signed in to your service. If the user isn't signed in, complete your service's sign-in or sign-up flow.

  3. Generate an access token for Google to use to access your API. The access token can be any string value, but it must uniquely represent the user and the client the token is for and must not be guessable.

  4. Send an HTTP response that redirects the user's browser to the URL specified by the redirect_uri parameter. Include all of the following parameters in the URL fragment:

    • access_token: The access token you just generated
    • token_type: The string bearer
    • state: The unmodified state value from the original request

    The following is an example of the resulting URL: 

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

Google's OAuth 2.0 redirect handler receives the access token and confirms that the state value hasn't changed. After Google has obtained an access token for your service, Google attaches the token to subsequent calls to your service APIs.

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

نقطه پایانی 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، پیکربندی کلیک کنید.
  2. در فیلد جریان OAuth ، گزینه Client-side را انتخاب کنید.
  3. در فیلد OAuth Endpoints ، گزینه Custom را انتخاب کنید.
  4. نقطه پایانی OAuth 2.0 خود و شناسه کلاینتی که به گوگل اختصاص داده‌اید را در فیلدهای مربوطه مشخص کنید.
  5. در بخش مرحله ۱ ، هیچ محدوده گوگلی را انتخاب نکنید. در عوض، این فیلد را خالی بگذارید یا یک محدوده معتبر برای سرور خود تایپ کنید (یا اگر از محدوده‌های OAuth استفاده نمی‌کنید، یک رشته دلخواه). وقتی کارتان تمام شد، روی Authorize APIs کلیک کنید.
  6. در بخش‌های مرحله ۲ و مرحله ۳ ، جریان OAuth 2.0 را بررسی کنید و تأیید کنید که هر مرحله طبق برنامه عمل می‌کند.

شما می‌توانید پیاده‌سازی خود را با استفاده از ابزار Google Account Linking Demo اعتبارسنجی کنید.

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

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