تنفيذ خادم OAuth 2.0

يجب أن يتضمّن كل عملية دمج مع 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:

    1. 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.
    2. 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.

This figure shows the steps for a user to link their Google account
            to your authentication system. The first screenshot shows
            user-initiated linking from your platform. The second image shows
            user sign-in to Google, while the third shows the user consent and
            confirmation for linking their Google account with your app. The
            final screenshot shows a successfully linked user account in the
            Google app.
Figure 1. Account linking user sign in to Google and consent screens.

Requirements

  1. You must communicate that the user’s account will be linked to Google, not a specific Google product like Google Home or Google Assistant.
  2. 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.
  3. You must provide a way for users to go back or cancel, if they choose not to link.
  4. 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:

  1. Display Google's Privacy Policy. Include a link to Google’s Privacy Policy on the consent screen.

  2. Data to be shared. Use clear and concise language to tell the user what data of theirs Google requires and why.

  3. 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.

  4. 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.

  5. 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.
  6. 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 تتّبع الخطوات التالية:

  1. تفتح Google نقطة نهاية التفويض في متصفّح المستخدم. إذا بدأ الإجراء على جهاز مزوّد بميزات صوتية فقط، تنقل Google عملية تنفيذه إلى هاتف.
  2. يسجّل المستخدم الدخول، إذا لم يكن مسجّلاً الدخول، ويمنح Google الإذن بالوصول إلى بياناته باستخدام واجهة برمجة التطبيقات، إذا لم يسبق له منح الإذن.
  3. تنشئ خدمتك رمز تفويض وتُعيده إلى Google. لإجراء ذلك، عليك إعادة توجيه متصفح المستخدم إلى Google مع إرفاق رمز التفويض بالطلب.
  4. تُرسِل Google رمز التفويض إلى نقطة نهاية تبادل الرموز المميّزة التي تُجري عمليات التحقّق من صحة الرمز وتُصدر رمز دخول ورمز إعادة تحميل. رمز الوصول هو رمز مميّز قصير الأمد تقبله خدمتك كبيانات اعتماد للوصول إلى واجهات برمجة التطبيقات. الرمز المميّز للتحديث هو رمز مميّز دائم يمكن أن تخزّنه Google وتستخدمه للحصول على رموز دخول جديدة عند انتهاء صلاحيتها.
  5. بعد أن يُكمل المستخدم عملية ربط الحساب، يحتوي كل طلب يليه يتم إرساله من 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

لكي تتمكّن نقطة نهاية التفويض من معالجة طلبات تسجيل الدخول، عليك اتّباع الخطوات التالية:

  1. تأكَّد من أنّ client_id يتطابق مع معرّف العميل الذي حدّدته لشركة Google، وأنّ redirect_uri يتطابق مع عنوان URL لإعادة التوجيه الذي قدّمته Google لخدمتك. هذه عمليات التحقّق مهمة لمنع منح إذن الوصول إلى تطبيقات العميل غير المقصودة أو التي تم ضبط إعداداتها بشكلٍ خاطئ. إذا كنت تتيح استخدام مسارات متعددة لبروتوكول OAuth 2.0، تأكَّد أيضًا من أنّ القيمة response_type هي code.
  2. تحقَّق مما إذا كان المستخدم مسجِّلاً الدخول إلى خدمتك. إذا لم يكن المستخدم مسجِّلاً الدخول، أكمِل خطوات تسجيل الدخول أو الاشتراك في الخدمة.
  3. أنشئ رمز تفويض لاستخدامه في Google للوصول إلى واجهة برمجة التطبيقات. يمكن أن يكون رمز التفويض أي قيمة سلسلة، ولكن يجب أن يمثّل بشكل فريد المستخدم والعميل الذي يخصّه الرمز المميّز ووقت انتهاء صلاحية الرمز، ويجب ألا يكون قابلاً للتخمين. عادةً ما تُصدر رموًا مخصّصة للسماح بالوصول تنتهي صلاحيتها بعد 10 دقائق تقريبًا.
  4. تأكَّد من أنّ عنوان URL المحدّد بالمَعلمة redirect_uri يحتوي على الشكل التالي:
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
      https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
      
  5. إعادة توجيه متصفّح المستخدم إلى عنوان 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 على النحو التالي:

الانتقال إلى Play Console

  1. من قائمة المشاريع، انقر على فتح بجانب المشروع الذي تريد العمل عليه.

  2. ضمن من السحابة الإلكترونية إلى السحابة الإلكترونية، اختَر تطوير.

  3. انقر على فتح بجانب عملية الدمج.

  4. انتقِل للأسفل إلى قسم الأذونات (اختيارية) وضَع علامة في مربّع الاختيار إرسال Google لمعرّف العميل والسرية من خلال عنوان المصادقة الأساسية لبروتوكول HTTP.

  5. انقر على حفظ لحفظ التغييرات.

تبديل رموز التفويض برموز الدخول والرموز المميّزة لإعادة التحميل

بعد تسجيل دخول المستخدم وعرض نقطة نهاية التفويض رمز تفويض قصير الأجل على 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 من خلال تنفيذ الخطوات التالية:

  1. تأكَّد من أنّ client_id يحدِّد مصدر الطلب كمصدر مفوَّض، وأنّ client_secret يتطابق مع القيمة المتوقّعة.
  2. تأكَّد من أنّ رمز التفويض صالح ولم تنته صلاحيته، وأنّ رقم تعريف العميل المحدّد في الطلب يتطابق مع رقم تعريف العميل المرتبط برمز التفويض.
  3. تأكَّد من أنّ عنوان URL المحدّد بالمَعلمة redirect_uri مطابق للقيمة المستخدَمة في طلب التفويض الأوّلي.
  4. إذا تعذّر عليك التحقّق من جميع المعايير أعلاه، يجب عرض خطأ HTTP 400 Bad Request مع {"error": "invalid_grant"} كنص.
  5. بخلاف ذلك، استخدِم رقم تعريف المستخدم من رمز التفويض لإنشاء رمز مميَّز لإعادة التحميل ورمز مميَّز للوصول. يمكن أن تكون هذه الرموز المميّزة أي قيمة سلسلة، ولكن يجب أن تمثل بشكل فريد المستخدم والعميل المخصّص له الرمز المميّز، ويجب أن يكون من الصعب تخمينها. بالنسبة إلى رموز الوصول، سجِّل أيضًا وقت انتهاء صلاحية الرمز، والذي يكون عادةً بعد ساعة من إصدار الرمز. لا تنتهي صلاحية الرموز المميّزة لإعادة التحميل.
  6. عرض عنصر 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 من خلال تنفيذ الخطوات التالية:

  1. تأكَّد من أنّ client_id يحدِّد مصدر الطلب على أنّه Google، وأنّ client_secret يتطابق مع القيمة المتوقّعة.
  2. تأكَّد من أنّ رمز إعادة التنشيط صالح، ومن أنّ معرّف العميل المحدّد في الطلب يتطابق مع معرّف العميل المرتبط برمز إعادة التنشيط.
  3. إذا تعذّر عليك التحقّق من جميع المعايير أعلاه، يجب عرض خطأ HTTP 400 Bad Request مع {"error": "invalid_grant"} كنص.
  4. بخلاف ذلك، استخدِم رقم تعريف المستخدم من الرمز المميَّز لإعادة التحميل لإنشاء رمز مميَّز للوصول. يمكن أن تكون هذه الرموز المميّزة أي قيمة سلسلة، ولكن يجب أن تمثل بشكل فريد المستخدم والعميل المخصّص له الرمز المميّز، ويجب ألّا يكون يمكن تخمينها. بالنسبة إلى رموز الوصول، سجِّل أيضًا وقت انتهاء صلاحية الرمز، وهو عادةً ما يكون بعد ساعة من إصدار الرمز.
  5. عرض عنصر 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:

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:

  1. Extract access token from the Authorization header and return information for the user associated with the access token.
  2. 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:
    HTTP/1.1 401 Unauthorized
    WWW-Authenticate: error="invalid_token",
    error_description="The Access Token expired"
    
    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.
  3. If the access token is valid, return and HTTP 200 response with the following JSON object in the body of the HTTPS response:

    {
    "sub": "USER_UUID",
    "email": "EMAIL_ADDRESS",
    "given_name": "FIRST_NAME",
    "family_name": "LAST_NAME",
    "name": "FULL_NAME",
    "picture": "PROFILE_PICTURE",
    }
    If your userinfo endpoint returns an HTTP 200 success response, the retrieved token and claims are registered against the user's Google account.

    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.