Overview

Every smart home Action must include a mechanism for authenticating users.

Authentication allows you to link your users' Google accounts with user accounts in your authentication system. This allows you to identify your users when your fulfillment receives a smart home intent. Google smart home only supports OAuth with an authorization code flow.

موجهات التصميم

يصف هذا القسم متطلبات التصميم والتوصيات الخاصة بشاشة الموافقة التي تربط حساب App Flip. بعد أن تتصل Google بتطبيقك ، يعرض التطبيق شاشة الموافقة للمستخدم.

متطلبات

  1. يجب أن تبلغ أن حساب المستخدم مرتبط بحساب Google ، وليس بمنتج معين من منتجات Google ، مثل صفحة Google الرئيسية أو مساعد Google.

التوصيات

نوصي بالقيام بما يلي:

  1. اعرض سياسة خصوصية Google. قم بتضمين رابط لسياسة خصوصية Google على شاشة الموافقة.

  2. البيانات المراد تقاسمها. استخدم لغة واضحة وموجزة لإخبار المستخدم بالبيانات التي تتطلبها Google ولماذا.

  3. مسح عبارة الحث على اتخاذ إجراء. حدد عبارة واضحة تحث المستخدم على اتخاذ إجراء على شاشة موافقتك ، مثل "أوافق واربط" هذا لأن المستخدمين بحاجة إلى فهم البيانات التي يتعين عليهم مشاركتها مع Google لربط حساباتهم.

  4. القدرة على الإلغاء. وفر طريقة للمستخدمين للعودة أو الإلغاء ، إذا اختاروا عدم الارتباط.

  5. القدرة على فك الارتباط. قدم آلية للمستخدمين لإلغاء الارتباط ، مثل عنوان URL لإعدادات حساباتهم على النظام الأساسي الخاص بك. بدلاً من ذلك ، يمكنك تضمين رابط إلى حساب Google حيث يمكن للمستخدمين إدارة حساباتهم المرتبطة.

  6. القدرة على تغيير حساب المستخدم. اقترح طريقة للمستخدمين لتبديل حساباتهم. هذا مفيد بشكل خاص إذا كان المستخدمون يميلون إلى امتلاك حسابات متعددة.

    • إذا كان يجب على المستخدم إغلاق شاشة الموافقة لتبديل الحسابات ، فأرسل خطأً قابلاً للاسترداد إلى Google حتى يتمكن المستخدم من تسجيل الدخول إلى الحساب المطلوب من خلال ربط OAuth والتدفق الضمني .
  7. قم بتضمين شعارك. اعرض شعار شركتك على شاشة الموافقة. استخدم إرشادات أسلوبك لوضع شعارك. إذا كنت ترغب أيضًا في عرض شعار Google ، فراجع الشعارات والعلامات التجارية .

يوضح هذا الشكل مثالاً لشاشة الموافقة مع استدعاءات للمتطلبات والتوصيات الفردية التي يجب اتباعها عند تصميم شاشة موافقة المستخدم.
الشكل 2. إرشادات تصميم شاشة الموافقة التي تربط الحساب.

Implement OAuth account linking

To implement OAuth account linking in your smart home Action, you must do the following:

  1. Implement your OAuth 2.0 server.
  2. Configure account linking in the Actions console.

Implement your OAuth 2.0 server

This section describes how to set up your OAuth 2.0 server so that it works with your smart home Action.

يتكون تنفيذ خادم 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 الذي سجلته لدى 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 الذي قمت بتسجيله في Google ، وأن redirect_uri يطابق عنوان URL لإعادة التوجيه المقدم من Google client_id . هذه الفحوصات مهمة لمنع منح الوصول إلى تطبيقات العميل غير المقصودة أو المهيأة بشكل خاطئ. إذا كنت تدعم تدفقات OAuth 2.0 المتعددة ، فتأكد أيضًا من أن نوع response_type هو code .
  2. تحقق مما إذا كان المستخدم قد قام بتسجيل الدخول إلى خدمتك. إذا لم يقم المستخدم بتسجيل الدخول ، أكمل عملية تسجيل الدخول أو تسجيل الاشتراك في الخدمة.
  3. قم بإنشاء رمز تفويض لـ Google لاستخدامه في الوصول إلى API الخاص بك. يمكن أن يكون رمز التفويض أي قيمة سلسلة ، ولكن يجب أن يمثل بشكل فريد المستخدم والعميل الذي يمثل الرمز المميز له ووقت انتهاء صلاحية الرمز ، ويجب ألا يكون قابلاً للتخمين. أنت تُصدر عادةً رموز تفويض تنتهي صلاحيتها بعد 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 نوع الرمز الذي يتم تبادله. إما أن يكون refresh_token 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 طلبًا إلى نقطة نهاية تبادل الرموز الخاصة بك لتبادل رمز التفويض لرمز وصول ورمز مميز للتحديث.

بالنسبة إلى هذه الطلبات ، تكون قيمة نوع grant_type هي 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 عن طريق تنفيذ الخطوات التالية:

  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
    }

Configure account linking in the console

To set up account linking in the Actions console, follow these steps:

  1. Go to the Actions console.
  2. Select your smart home Action project.
  3. Click the Develop tab. Then, click Account linking in the left navigation.
  4. Fill out all the fields under OAuth Client information. Click Next.
  5. Click Save.

Next steps (optional)

Once you have an OAuth 2.0 implementation, you can optionally configure OAuth-based App Flip, which allows your users to more quickly link their accounts in your authentication system to their Google accounts. For App Flip implementation instructions, see OAuth-based App Flip.