يجب أن يتضمّن كل عملية دمج مع Cloud-to-cloud آلية لسماح بالوصول إلى حسابات المستخدمين.
تتيح لك المصادقة ربط حسابات المستخدمين على Google بحسابات المستخدمين في نظام المصادقة. يتيح لك ذلك تحديد المستخدمين عندماتلقّى Fulfillment طلبًا مرتبطًا بالمنزل الذكي. لا تتيح ميزة "المنزل الذكي من Google" استخدام بروتوكول OAuth إلا مع مسار رمز التفويض.
توضِّح هذه الصفحة كيفية إعداد خادم OAuth 2.0 لكي يعمل مع عملية دمج Cloud-to-cloud.
ربط حساب Google باستخدام بروتوكول OAuth
In the authorization code flow, you need two endpoints:
The authorization endpoint, which presents the sign-in UI to your users that aren't already signed in. The authorization endpoint also creates a short-lived authorization code to record users' consent to the requested access.
The token exchange endpoint, which is responsible for two types of exchanges:
- Exchanges an authorization code for a long-lived refresh token and a short-lived access token. This exchange happens when the user goes through the account linking flow.
- Exchanges a long-lived refresh token for a short-lived access token. This exchange happens when Google needs a new access token because the one it had expired.
Design guidelines
This section describes the design requirements and recommendations for the user screen that you host for OAuth linking flows. After it's called by Google's app, your platform displays a sign in to Google page and account linking consent screen to the user. The user is directed back to Google's app after giving their consent to link accounts.

Requirements
- You must communicate that the user’s account will be linked to Google, not a specific Google product like Google Home or Google Assistant.
- You must have a Google authorization statement such as "By signing in, you are authorizing Google to control your devices." See the Google Device Control Authorization section of the Google Home Developer Policies.
- You must provide a way for users to go back or cancel, if they choose not to link.
- You must open the Web OAuth linking page and ensure users have a clear method for signing in to their Google Account, such as fields for their username and password. Don't use the Google Sign-In (GSI) method that enables users to link without being taken to the Web OAuth Linking page. It is a violation of Google policy.
Recommendations
We recommend that you do the following:
Display Google's Privacy Policy. Include a link to Google’s Privacy Policy on the consent screen.
Data to be shared. Use clear and concise language to tell the user what data of theirs Google requires and why.
Clear call-to-action. State a clear call-to-action on your consent screen, such as “Agree and link.” This is because users need to understand what data they're required to share with Google to link their accounts.
Ability to unlink. Offer a mechanism for users to unlink, such as a URL to their account settings on your platform. Alternatively, you can include a link to Google Account where users can manage their linked account.
Ability to change user account. Suggest a method for users to switch their account(s). This is especially beneficial if users tend to have multiple accounts.
- If a user must close the consent screen to switch accounts, send a recoverable error to Google so the user can sign in to the desired account with OAuth linking.
Include your logo. Display your company logo on the consent screen. Use your style guidelines to place your logo. If you wish to also display Google's logo, see Logos and trademarks.

مسار رمز التفويض
يتألّف تنفيذ خادم OAuth 2.0 لمسار رمز التفويض من نقطتَي نهاية توفّرها خدمتك من خلال بروتوكول HTTPS. نقطة النهاية الأولى هي نقطة نهاية التفويض، وهي المسؤولة عن العثور على موافقة من المستخدمين للوصول إلى البيانات أو الحصول عليها. تعرِض نقطة نهاية التفويض واجهة مستخدم تسجيل دخول للمستخدمين الذين لم يسجّلوا الدخول بعد، وتسجِّل الموافقة على الوصول المطلوب. نقطة النهاية الثانية هي نقطة نهاية تبادل الرموز المميّزة، والتي تُستخدَم للحصول على سلاسل مشفّرة تُعرف باسم الرموز المميّزة، والتي تمنح المستخدم إذنًا بالوصول إلى خدمتك.
عندما يحتاج أحد تطبيقات Google إلى طلب بيانات من إحدى واجهات برمجة تطبيقات خدمتك، تستخدم Google نقاط النهاية هذه معًا للحصول على إذن من المستخدمين لطلب بيانات من واجهات برمجة التطبيقات هذه نيابةً عنهم.
إنّ جلسة مسار رمز التفويض في OAuth 2.0 التي تبدأها Google تتّبع الخطوات التالية:
- تفتح Google نقطة نهاية التفويض في متصفّح المستخدم. إذا بدأ الإجراء على جهاز مزوّد بميزات صوتية فقط، تنقل Google عملية تنفيذه إلى هاتف.
- يسجّل المستخدم الدخول، إذا لم يكن مسجّلاً الدخول، ويمنح Google الإذن بالوصول إلى بياناته باستخدام واجهة برمجة التطبيقات، إذا لم يسبق له منح الإذن.
- تنشئ خدمتك رمز تفويض وتُعيده إلى Google. لإجراء ذلك، عليك إعادة توجيه متصفح المستخدم إلى Google مع إرفاق رمز التفويض بالطلب.
- تُرسِل Google رمز التفويض إلى نقطة نهاية تبادل الرموز المميّزة التي تُجري عمليات التحقّق من صحة الرمز وتُصدر رمز دخول ورمز إعادة تحميل. رمز الوصول هو رمز مميّز قصير الأمد تقبله خدمتك كبيانات اعتماد للوصول إلى واجهات برمجة التطبيقات. الرمز المميّز للتحديث هو رمز مميّز دائم يمكن أن تخزّنه Google وتستخدمه للحصول على رموز دخول جديدة عند انتهاء صلاحيتها.
- بعد أن يُكمل المستخدم عملية ربط الحساب، يحتوي كل طلب يليه يتم إرساله من Google على رمز مميّز للوصول.
معالجة طلبات التفويض
عندما تحتاج إلى إجراء عملية ربط الحساب باستخدام مسار رمز التفويض في OAuth 2.0، تُرسِل Google المستخدم إلى نقطة نهاية التفويض مع طلب يحتوي على المَعلمات التالية:
مَعلمات نقطة نهاية التفويض | |
---|---|
client_id |
معرّف العميل الذي تمّ تعيينه لشركة Google. |
redirect_uri |
عنوان URL الذي تُرسِل إليه الردّ على هذا الطلب. |
state |
قيمة محاسبية يتم تمريرها إلى Google بدون تغيير في معرّف الموارد المنتظم (URI) لإعادة التوجيه. |
scope |
اختياري: مجموعة من سلاسل النطاقات مفصولة بمسافات تحدِّد البيانات التي تطلب Google الحصول على إذن بها. |
response_type |
نوع القيمة المطلوب عرضها في الاستجابة بالنسبة إلى مسار رمز التفويض في OAuth 2.0، يكون نوع الردّ دائمًا code .
|
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&scope=REQUESTED_SCOPES&response_type=code&user_locale=LOCALE
لكي تتمكّن نقطة نهاية التفويض من معالجة طلبات تسجيل الدخول، عليك اتّباع الخطوات التالية:
- تأكَّد من أنّ
client_id
يتطابق مع معرّف العميل الذي حدّدته لشركة Google، وأنّredirect_uri
يتطابق مع عنوان URL لإعادة التوجيه الذي قدّمته Google لخدمتك. هذه عمليات التحقّق مهمة لمنع منح إذن الوصول إلى تطبيقات العميل غير المقصودة أو التي تم ضبط إعداداتها بشكلٍ خاطئ. إذا كنت تتيح استخدام مسارات متعددة لبروتوكول OAuth 2.0، تأكَّد أيضًا من أنّ القيمةresponse_type
هيcode
. - تحقَّق مما إذا كان المستخدم مسجِّلاً الدخول إلى خدمتك. إذا لم يكن المستخدم مسجِّلاً الدخول، أكمِل خطوات تسجيل الدخول أو الاشتراك في الخدمة.
- أنشئ رمز تفويض لاستخدامه في Google للوصول إلى واجهة برمجة التطبيقات. يمكن أن يكون رمز التفويض أي قيمة سلسلة، ولكن يجب أن يمثّل بشكل فريد المستخدم والعميل الذي يخصّه الرمز المميّز ووقت انتهاء صلاحية الرمز، ويجب ألا يكون قابلاً للتخمين. عادةً ما تُصدر رموًا مخصّصة للسماح بالوصول تنتهي صلاحيتها بعد 10 دقائق تقريبًا.
- تأكَّد من أنّ عنوان URL المحدّد بالمَعلمة
redirect_uri
يحتوي على الشكل التالي:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
- إعادة توجيه متصفّح المستخدم إلى عنوان URL المحدّد بالمَعلمة
redirect_uri
أدرِج رمز التفويض الذي أنشأته للتو وقيمة الحالة الأصلية غير المعدَّلة عند إعادة التوجيه من خلال إلحاق المَعلمتَينcode
وstate
. في ما يلي مثال على عنوان URL الناتج:https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING
معالجة طلبات استبدال الرموز المميّزة
تتحمّل نقطة نهاية تبادل الرموز المميّزة في خدمتك مسؤولية نوعَين من عمليات مبادلة الرموز المميّزة:
- تبديل رموز التفويض برموز الدخول والرموز المميّزة لإعادة التحميل
- استبدال الرموز المميّزة لإعادة التحميل برموز الدخول
تتضمّن طلبات استبدال الرموز المميّزة المَعلمات التالية:
مَعلمات نقطة نهاية تبادل الرموز المميّزة | |
---|---|
client_id |
سلسلة تُحدِّد مصدر الطلب على أنّه Google يجب تسجيل هذه السلسلة في نظامك كمعرّف فريد من Google. |
client_secret |
سلسلة سرية سجّلتها باستخدام Google للخدمة التي تقدّمها. |
grant_type |
نوع الرمز المميّز الذي يتمّ تبادله إما
authorization_code أو refresh_token . |
code |
عندما تكون القيمة grant_type=authorization_code ، تكون هذه المَعلمة هي
الرمز الذي تلقّته Google من نقطة نهاية تسجيل الدخول أو نقطة نهاية تبادل الرموز المميّزة. |
redirect_uri |
عندما يكون القيمة grant_type=authorization_code ، تكون هذه المَعلمة هي عنوان URL
المستخدَم في طلب التفويض الأوّلي. |
refresh_token |
عندما تكون القيمة grant_type=refresh_token ، تكون هذه المَعلمة هي
الرمز المميّز لإعادة التحميل الذي تلقّته Google من نقطة نهاية تبادل الرموز المميّزة. |
ضبط كيفية إرسال Google لبيانات الاعتماد إلى خادمك
استنادًا إلى طريقة تنفيذه، يتوقّع خادم التفويض تلقّي بيانات اعتماد العميل إما في نص الطلب أو في عنوانه.
ترسل Google بيانات الاعتماد تلقائيًا في نص الطلب. إذا كان خادم التفويض يتطلّب أن تكون بيانات اعتماد العميل في عنوان الطلب، عليك ضبط عملية دمج Cloud-to-cloud على النحو التالي:
من قائمة المشاريع، انقر على فتح بجانب المشروع الذي تريد العمل عليه.
ضمن من السحابة الإلكترونية إلى السحابة الإلكترونية، اختَر تطوير.
انقر على فتح بجانب عملية الدمج.
انتقِل للأسفل إلى قسم الأذونات (اختيارية) وضَع علامة في مربّع الاختيار إرسال Google لمعرّف العميل والسرية من خلال عنوان المصادقة الأساسية لبروتوكول HTTP.
انقر على حفظ لحفظ التغييرات.
تبديل رموز التفويض برموز الدخول والرموز المميّزة لإعادة التحميل
بعد تسجيل دخول المستخدم وعرض نقطة نهاية التفويض رمز تفويض قصير الأجل على Google، تُرسِل Google طلبًا إلى نقطة نهاية تبادل الرمز المميّز لاستبدال رمز التفويض برمز دخول ورمز مميّز لإعادة التحميل.
بالنسبة إلى هذه الطلبات، تكون قيمة grant_type
هي authorization_code
، وتكون قيمة code
هي قيمة رمز التفويض الذي منحته سابقًا
إلى Google. في ما يلي مثال على طلب استبدال رمز
تفويض برمز دخول ورمز مميز لإعادة التحميل:
POST /token HTTP/1.1 Host: oauth2.example.com Content-Type: application/x-www-form-urlencoded client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI
لتبديل رموز التفويض برمز دخول ورمز إعادة تحميل، تستجيب
نقطة نهاية تبادل الرموز المميّزة لطلبات POST
من خلال تنفيذ الخطوات التالية:
- تأكَّد من أنّ
client_id
يحدِّد مصدر الطلب كمصدر مفوَّض، وأنّclient_secret
يتطابق مع القيمة المتوقّعة. - تأكَّد من أنّ رمز التفويض صالح ولم تنته صلاحيته، وأنّ رقم تعريف العميل المحدّد في الطلب يتطابق مع رقم تعريف العميل المرتبط برمز التفويض.
- تأكَّد من أنّ عنوان URL المحدّد بالمَعلمة
redirect_uri
مطابق للقيمة المستخدَمة في طلب التفويض الأوّلي. - إذا تعذّر عليك التحقّق من جميع المعايير أعلاه، يجب عرض خطأ HTTP
400 Bad Request مع
{"error": "invalid_grant"}
كنص. - بخلاف ذلك، استخدِم رقم تعريف المستخدم من رمز التفويض لإنشاء رمز مميَّز لإعادة التحميل ورمز مميَّز للوصول. يمكن أن تكون هذه الرموز المميّزة أي قيمة سلسلة، ولكن يجب أن تمثل بشكل فريد المستخدم والعميل المخصّص له الرمز المميّز، ويجب أن يكون من الصعب تخمينها. بالنسبة إلى رموز الوصول، سجِّل أيضًا وقت انتهاء صلاحية الرمز، والذي يكون عادةً بعد ساعة من إصدار الرمز. لا تنتهي صلاحية الرموز المميّزة لإعادة التحميل.
- عرض عنصر JSON التالي في نص استجابة HTTPS:
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "refresh_token": "REFRESH_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
تخزِّن Google رمزَي الدخول المميّز وإعادة التحميل للمستخدم وتسجِّل انتهاء صلاحية رمز الدخول المميّز. عندما تنتهي صلاحية رمز الدخول، تستخدم Google رمز إعادة التحميل للحصول على رمز دخول جديد من نقطة نهاية تبادل الرموز المميّزة.
استبدال الرموز المميّزة لإعادة التحميل برموز الدخول
عند انتهاء صلاحية رمز دخول، ترسل Google طلبًا إلى نقطة نهاية تبادل الرموز المميّزة لاستبدال رمز مميّز لإعادة التحميل برمز دخول جديد.
بالنسبة إلى هذه الطلبات، تكون قيمة grant_type
هي refresh_token
، وتكون قيمة
refresh_token
هي قيمة الرمز المميّز لإعادة التحميل الذي منحته سابقًا ل
Google. في ما يلي مثال على طلب استبدال رمز إعادة التحميل
برمز دخول:
POST /token HTTP/1.1 Host: oauth2.example.com Content-Type: application/x-www-form-urlencoded client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN
لتبادل رمز إعادة التحميل للحصول على رمز دخول مميّز، يجب أن تستجيب نقطة نهاية تبادل الرموز المميّزةPOST
لطلبات POST
من خلال تنفيذ الخطوات التالية:
- تأكَّد من أنّ
client_id
يحدِّد مصدر الطلب على أنّه Google، وأنّclient_secret
يتطابق مع القيمة المتوقّعة. - تأكَّد من أنّ رمز إعادة التنشيط صالح، ومن أنّ معرّف العميل المحدّد في الطلب يتطابق مع معرّف العميل المرتبط برمز إعادة التنشيط.
- إذا تعذّر عليك التحقّق من جميع المعايير أعلاه، يجب عرض خطأ HTTP 400
Bad Request مع
{"error": "invalid_grant"}
كنص. - بخلاف ذلك، استخدِم رقم تعريف المستخدم من الرمز المميَّز لإعادة التحميل لإنشاء رمز مميَّز للوصول. يمكن أن تكون هذه الرموز المميّزة أي قيمة سلسلة، ولكن يجب أن تمثل بشكل فريد المستخدم والعميل المخصّص له الرمز المميّز، ويجب ألّا يكون يمكن تخمينها. بالنسبة إلى رموز الوصول، سجِّل أيضًا وقت انتهاء صلاحية الرمز، وهو عادةً ما يكون بعد ساعة من إصدار الرمز.
- عرض عنصر JSON التالي في نص استجابة HTTPS:
{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "expires_in": SECONDS_TO_EXPIRATION }
Handle userinfo requests
The userinfo endpoint is an OAuth 2.0 protected resource that return claims about the linked user. Implementing and hosting the userinfo endpoint is optional, except for the following use cases:
- Linked Account Sign-In with Google One Tap.
- Frictionless subscription on AndroidTV.
After the access token has been successfully retrieved from your token endpoint, Google sends a request to your userinfo endpoint to retrieve basic profile information about the linked user.
userinfo endpoint request headers | |
---|---|
Authorization header |
The access token of type Bearer. |
For example, if your userinfo endpoint is available at
https://myservice.example.com/userinfo
, a request might look like the following:
GET /userinfo HTTP/1.1 Host: myservice.example.com Authorization: Bearer ACCESS_TOKEN
For your userinfo endpoint to handle requests, do the following steps:
- Extract access token from the Authorization header and return information for the user associated with the access token.
- If the access token is invalid, return an HTTP 401 Unauthorized error with using the
WWW-Authenticate
Response Header. Below is an example of a userinfo error response: If a 401 Unauthorized, or any other unsuccessful error response is returned during the linking process, the error will be non-recoverable, the retrieved token will be discarded and the user will have to initiate the linking process again.HTTP/1.1 401 Unauthorized WWW-Authenticate: error="invalid_token", error_description="The Access Token expired"
If the access token is valid, return and HTTP 200 response with the following JSON object in the body of the HTTPS response:
If your userinfo endpoint returns an HTTP 200 success response, the retrieved token and claims are registered against the user's Google account.{ "sub": "USER_UUID", "email": "EMAIL_ADDRESS", "given_name": "FIRST_NAME", "family_name": "LAST_NAME", "name": "FULL_NAME", "picture": "PROFILE_PICTURE", }
userinfo endpoint response sub
A unique ID that identifies the user in your system. email
Email address of the user. given_name
Optional: First name of the user. family_name
Optional: Last name of the user. name
Optional: Full name of the user. picture
Optional: Profile picture of the user.