تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
يدعم نوع ربط OAuth تدفقين من تدفقات OAuth 2.0 المتوافقة مع معايير الصناعة: المساران الضمني ورمز التفويض. خلال مسار الرمز الضمني، تفتح Google نقطة نهاية التفويض في متصفّح المستخدم. بعد تسجيل الدخول بنجاح،
تُرجع رمز دخول طويل الأمد إلى Google. بعد ذلك، يتم تضمين رمز الدخول هذا
في كل طلب يتم إرساله من "مساعد Google" إلى الإجراء الخاص بك.
ويُعدّ ربط OAuth هو الحل المقترَح لربط الحساب في حال انطباق ما يلي:
لديك تطبيق حالي لخادم OAuth 2.0 ولا يمكنك تمديد نقطة نهاية تبادل الرمز المميز لإضافة دعم لبروتوكولات Google من أجل الربط التلقائي وإنشاء الحساب من الرمز المميز للمعرّف (أي إضافة معلمتي
intent=get وintent=create في الطلبات إلى نقطة النهاية هذه).
للتأكّد من أنّ ربط OAuth هو الحل المناسب لك، يُرجى الاطّلاع على صفحة
اختيار نوع ربط الحساب.
المصطلحات الرئيسية
قبل قراءة آلية عمل ربط OAuth، اطّلِع على البنود التالية:
user.verificationStatus: موقع يحدّده النظام للإشارة إلى ما إذا كانت الجلسة الحالية تتضمن مستخدمًا تم التحقق من هويته وأهليته.
user.accountLinkingStatus: سمة يحدّدها النظام للإشارة إلى ما إذا كان المستخدم في الجلسة الحالية لديه هوية مرتبطة.
مشهد نظام ربط الحسابات: مشهد محدد مسبقًا ينفّذ تدفق التأكيد لربط الحساب، ويمكن تخصيصه بما يتناسب مع حالات استخدام معيّنة.
مسار رمز التفويض: خلال مسار OAuth 2.0 هذا، تفتح Google
نقطة نهاية التفويض في متصفّح المستخدم. إذا تم تسجيل الدخول بنجاح،
تنشئ الخدمة رمز تفويض وتعيده إلى Google.
ترسل Google رمز التفويض هذا إلى نقطة نهاية تبادل الرموز المميّزة، التي تتحقّق من صحة الرمز وتعرض رمز الدخول والرمز المميّز لإعادة التحميل.
يتطلب هذا التدفق نقطتَي نهاية:
نقطة نهاية التفويض: نقطة النهاية المسؤولة عن إيجاد
موافقة المستخدمين على الوصول إلى البيانات أو الحصول عليها. تنفّذ نقطة النهاية هذه ما يلي:
يعرض واجهة المستخدم لتسجيل الدخول للمستخدمين الذين لم يسبق لهم تسجيل الدخول.
يسجل هذا الحقل الموافقة على الوصول المطلوب في شكل رمز تفويض قصير الأجل.
نقطة نهاية تبادل الرموز المميّزة: تُستخدَم نقطة النهاية هذه للحصول على سلاسل
مشفَّرة تُعرف باسم الرموز المميّزة والتي تسمح لمستخدم "الإجراء" بالوصول إلى خدمتك. نقطة النهاية هذه مسؤولة عن نوعَين من التبادلات:
تتبادل رمز التفويض مع رمز مميّز طويل الأمد لإعادة التحميل
ورمز دخول قصير الأجل. يحدث هذا التبادل عندما يمر المستخدم
بعملية ربط الحساب.
تتبادل الرمز المميّز لإعادة التحميل طويل الأمد مع رمز دخول قصير الأجل. يحدث التبادل هذا عندما تحتاج Google إلى رمز دخول جديد
بسبب انتهاء صلاحيته.
مسار الرمز الضمني: خلال مسار OAuth 2.0 هذا، تفتح Google نقطة نهاية التفويض في متصفّح المستخدِم. إذا تم تسجيل الدخول بنجاح، يتم إرجاع رمز دخول طويل الأمد إلى Google. بعد ذلك، يتم تضمين رمز الدخول هذا في
كل طلب يتم إرساله من "مساعد Google" إلى الإجراء الخاص بك. لا يتطلب هذا التدفق
سوى نقطة نهاية التفويض.
رمز الدخول: رمز مميز يفوّض خدمتك بالوصول إلى أجزاء من بيانات المستخدم. ترتبط رموز الدخول بكل مستخدم فردي
ويجب أن تكون غير قابلة للتخمين.
رمز إعادة التحميل المميّز: رمز مميّز يتم استبداله برمز دخول جديد بعد انتهاء صلاحية رمز دخول قصير الأجل.
آلية العمل
يصف هذا القسم التدفق العام لرمز تفويض OAuth والتدفقات الضمنية. يصف القسم التالي، تدفقات ربط OAuth، العمليات المختلفة التي يمكن أن تحدث مع OAuth.
يمكن تلخيص مسار رمز التفويض كما يلي:
يسأل الإجراء الخاص بك المستخدم عمّا إذا كان يريد ربط حسابه بخدمتك.
بعد موافقة المستخدم على ربط الحسابات، تفتح Google نقطة نهاية التفويض في متصفّح المستخدم. وإذا بدأ المسار على جهاز مخصّص للصوت فقط
لتنفيذ إجراء معيّن، ستنقل Google عملية التنفيذ إلى هاتف.
يسجِّل المستخدم الدخول (إذا لم يكن مسجّلاً الدخول من قبل) ويمنح Google الإذن بالوصول إلى بياناته باستخدام واجهة برمجة التطبيقات (إذا لم يحصل على إذن من قبل).
تنشئ الخدمة رمز تفويض وتعرضه إلى Google من خلال إعادة توجيه متصفّح المستخدم إلى Google مرة أخرى مع إرفاق رمز التفويض بالطلب.
ترسل Google رمز التفويض إلى نقطة نهاية تبادل الرموز المميّزة، التي تتحقّق من صحة الرمز وتعرض رمز دخول ورمزًا مميّزًا لإعادة التحميل. رمز الدخول هو رمز قصير الأجل تقبله خدمتك كبيانات اعتماد للوصول إلى واجهات برمجة التطبيقات. الرمز المميّز لإعادة التحميل هو رمز مميّز طويل الأمد يمكن أن تخزّنه Google وتستخدمه للحصول على رموز دخول جديدة عند انتهاء صلاحيتها.
بعد أن يكمل المستخدم عملية ربط الحساب، يحتوي كل طلب لاحق يتم إرساله من "مساعد Google" إلى الرد التلقائي على الويب الخاص بالتنفيذ على رمز دخول.
يمكن تلخيص تدفق التعليمات البرمجية الضمنية على النحو التالي:
يسأل الإجراء الخاص بك المستخدم عمّا إذا كان يريد ربط حسابه بخدمتك.
بعد موافقة المستخدم على ربط الحسابات، تفتح Google نقطة نهاية التفويض في متصفّح المستخدم.
يسجِّل المستخدم الدخول (إذا لم يكن مسجّلاً الدخول من قبل) ويمنح Google الإذن بالوصول إلى بياناته باستخدام واجهة برمجة التطبيقات (إذا لم يحصل على إذن من قبل).
تنشئ خدمتك رمز دخول وتعيده إلى Google من خلال إعادة توجيه متصفح المستخدم إلى Google باستخدام رمز الدخول المرفق بالطلب.
بعد أن يكمل المستخدم عملية ربط الحساب، تستدعي Google واجهات برمجة التطبيقات الخاصة بخدمتك وترفق رمز الدخول مع كل طلب. تتحقّق خدمتك
من أنّ رمز الدخول يمنح Google تفويضًا بالوصول إلى واجهة برمجة التطبيقات
ثم تُكمل طلب بيانات من واجهة برمجة التطبيقات.
يكون مسار رمز التفويض الأساسي على النحو التالي:
يسأل الإجراء الخاص بك المستخدم عمّا إذا كان يريد ربط حسابه بخدمتك.
بعد موافقة المستخدم على ربط الحسابات، تفتح Google نقطة نهاية التفويض في متصفّح المستخدم. وإذا بدأ المسار على جهاز مخصّص للصوت فقط
لتنفيذ إجراء معيّن، ستنقل Google عملية التنفيذ إلى هاتف.
يسجِّل المستخدم الدخول (إذا لم يكن مسجّلاً الدخول من قبل) ويمنح Google الإذن بالوصول إلى بياناته باستخدام واجهة برمجة التطبيقات (إذا لم يحصل على إذن من قبل).
تنشئ الخدمة رمز تفويض وتعيده إلى Google عن طريق
إعادة توجيه متصفح المستخدم إلى Google مرة أخرى باستخدام رمز التفويض قصير الأجل
المرفق بالطلب.
ترسل Google رمز التفويض إلى نقطة نهاية تبادل الرموز المميّزة، التي تتحقّق من صحة الرمز وتعرض رمز دخول ورمزًا مميّزًا لإعادة التحميل. رمز الدخول هو رمز قصير الأجل تقبله خدمتك كبيانات اعتماد للوصول إلى واجهات برمجة التطبيقات. الرمز المميّز لإعادة التحميل هو رمز مميّز طويل الأمد يمكن أن تخزّنه Google وتستخدمه للحصول على رموز دخول جديدة عند انتهاء صلاحيتها.
بعد أن يكمل المستخدم عملية ربط الحساب، يحتوي كل طلب لاحق يتم إرساله من "مساعد Google" إلى الرد التلقائي على الويب الخاص بالتنفيذ على رمز دخول.
مسارات ربط OAuth
يستعرض هذا القسم المسارات المختلفة التي يمكن أن تحدث مع ربط OAuth.
يتضمّن كل مسار هذه الخطوات الشائعة بعد استدعاء المستخدم للإجراء الخاص بك:
في التدفق أعلاه، تنتقل إلى مشهد نظام ربط الحسابات وتقدم مبررًا منطقيًا مخصصًا. يسأل "مساعد Google" المستخدم عمّا إذا كان يريد ربط حسابه بخدمتك ويعرض له شاشة بالأذونات المطلوبة. عندما يوافق المستخدم، ستعيد Google توجيه المستخدم إلى نقطة نهاية تفويض الخدمة في المتصفح. يسجّل المستخدم الدخول (أو ينشئ حسابًا جديدًا،
بناءً على عملية الضبط) ويمنح الإجراء
الإذن بالوصول إلى بياناته.
تختلف التدفقات بعد هذه النقطة اعتمادًا على ما إذا كنت قد نفذت
التدفق الضمني أو تدفق رمز التفويض أم لا. يتم وصف هذه التدفقات في
الأقسام التالية.
المسار 1: تسجيل دخول المستخدم من خلال تدفق ضمني
بعد تسجيل دخول المستخدم والتحقق من بيانات اعتماده، تنشئ الخدمة رمز دخول طويل الأمد وتعيده إلى Google. في هذه المرحلة، يتم ربط هوية المستخدم في الإجراء الخاص بك بالحساب الذي سجّل الدخول إليه، ويتم إرفاق رمز الدخول بكل طلب من استدعاءات Google لواجهات برمجة التطبيقات الخاصة بخدمتك.
المسار 2: تسجيل دخول المستخدم باستخدام مسار رمز التفويض
بعد تسجيل دخول المستخدم والتحقق من بيانات اعتماده، تنشئ الخدمة رمز تفويض وتعيده إلى Google.
يتم إرسال رمز التفويض هذا إلى نقطة نهاية تبادل الرمز المميّز، والتي تعرض كلاً من رمز الدخول ورمز إعادة التحميل. في هذه المرحلة، تكون هوية المستخدم في الإجراء الخاص بك مرتبطة بأي حساب سجّل الدخول إليه، ويحتوي كل طلب لاحق يتم إرساله من "مساعد Google" إلى تنفيذ الإجراء على رمز دخول.
تاريخ التعديل الأخير: 2025-07-25 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-07-25 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eOAuth linking in Google Assistant uses OAuth 2.0 for account linking, supporting both implicit and authorization code flows.\u003c/p\u003e\n"],["\u003cp\u003eImplicit flow directly returns a long-lived access token upon successful sign-in, while the authorization code flow involves an intermediary authorization code for enhanced security.\u003c/p\u003e\n"],["\u003cp\u003eAccount linking with OAuth is recommended when you have an existing OAuth 2.0 server and cannot modify its token exchange endpoint to accommodate Google's protocols.\u003c/p\u003e\n"],["\u003cp\u003eThe authorization code flow involves an authorization endpoint for user consent and a token exchange endpoint for acquiring access and refresh tokens.\u003c/p\u003e\n"],["\u003cp\u003eGoogle Assistant provides system properties like \u003ccode\u003euser.verificationStatus\u003c/code\u003e and \u003ccode\u003euser.accountLinkingStatus\u003c/code\u003e to indicate the user's verification and linking status, respectively.\u003c/p\u003e\n"]]],["OAuth linking utilizes the implicit and authorization code flows. In the implicit flow, after user sign-in, a long-lived access token is returned to Google, included in all subsequent requests. The authorization code flow involves Google receiving a short-lived authorization code after user sign-in, which is exchanged for an access and refresh token at the token exchange endpoint. Both flows begin with the user agreeing to link accounts and granting data access permission. After these steps, each service interaction from assistant will contain an access token.\n"],null,["# OAuth linking concept guide\n\nThe *OAuth linking* type supports two industry-standard OAuth 2.0 flows:\nthe *implicit* and *authorization code* flows. In the implicit code flow, Google\nopens your authorization endpoint in the user's browser. After successful sign-in,\nyou return a long-lived access token to Google. This access token is then included\nin every request sent from Assistant to your Action.\n\nOAuth linking is the recommended account linking solution if the following applies:\n\n- You have an existing implementation of an OAuth 2.0 server, and you cannot extend your token exchange endpoint to add support for Google's protocols for automatic linking and account creation from an ID token (i.e., add the `intent=get` and `intent=create` parameters in requests to this endpoint).\n\nTo verify that OAuth linking is the right solution for you, see the\n[Choose your account linking type](/assistant/identity/choose-type) page.\n\nKey terms\n---------\n\nBefore you read about how OAuth linking works, familiarize yourself with the following terms:\n\n- **`user.verificationStatus`:** A property set by the system to indicate if the\n current session has a verified user.\n\n- **`user.accountLinkingStatus`:** A property set by the system to indicate if the\n user in the current session has a linked identity.\n\n- **Account linking system scene:** A predefined scene that implements the confirmation\n flow for account linking, and can be customized to fit specific use cases.\n\n- **Authorization code flow:** During this OAuth 2.0 flow, Google opens your\n authorization endpoint in the user's browser. If sign-in is successful,\n your service creates an *authorization code* and returns it to Google.\n Google sends this authorization code to your token exchange endpoint, which\n verifies the authenticity of the code and returns an access token and refresh token.\n\n This flow requires two endpoints:\n - **Authorization endpoint:** The endpoint that is responsible for finding or obtaining consent from users for data access. This endpoint does the following:\n 1. Presents the sign-in UI to your users that aren't already signed in.\n 2. Records consent to the requested access in the form of a short-lived authorization code.\n - **Token exchange endpoint:** This endpoint is used to obtain encrypted strings called *tokens* that authorize the Action user to access your service. This endpoint is responsible for two types of exchanges:\n 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.\n 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.\n- **Implicit code flow:** During this OAuth 2.0 flow, Google opens your authorization\n endpoint in the user's browser. If sign-in is successful, you return a\n long-lived access token to Google. This access token is then included in\n every request sent from Assistant to your Action. This flow requires\n only an authorization endpoint.\n\n- **Access token:** A token that authorizes your service to access parts of\n a user's data. Access tokens are associated with each individual user\n and should be unguessable.\n\n- **Refresh token:** A token that is exchanged for a new access token once a\n short-lived access token has expired.\n\nHow it works\n------------\n\nThis section describes the general flow for the OAuth authorization code and\nimplicit flows. The following section, [OAuth linking flows](#oauth_linking_flows),\ndescribes the various flows that can occur with OAuth.\n\nThe authorization code flow can be summarized as follows:\n\n1. Your Action asks the user if they want to link their account with your service.\n2. After the user agrees to link accounts, Google opens your authorization endpoint in the user's browser. If the flow started on a voice-only device for an Action, Google would transfer the execution to a phone.\n3. 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).\n4. Your service creates an *authorization code* and returns it to Google by redirecting the user's browser back to Google with the authorization code attached to the request.\n5. Google sends the authorization code to your token exchange endpoint, which verifies the authenticity of the code and returns an *access token* and a *refresh token*. The access token is a short-lived token that your service accepts as credentials to access APIs. The refresh token is a long-lived token that Google can store and use to acquire new access tokens when they expire.\n6. After the user has completed the account linking flow, every subsequent request sent from Assistant to your fulfillment webhook contains an access token.\n\nThe implicit code flow can be summarized as follows:\n\n1. Your Action asks the user if they want to link their account with your service.\n2. After the user agrees to link accounts, Google opens your authorization endpoint in the user's browser.\n3. 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).\n4. Your service creates an access token and returns it to Google by redirecting the user's browser back to Google with the access token attached to the request.\n5. After the user has completed the account linking flow, 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.\n\nThe fundamental authorization code flow is as follows:\n\n1. Your Action asks the user if they want to link their account with your service.\n2. After the user agrees to link accounts, Google opens your authorization endpoint in the user's browser. If the flow started on a voice-only device for an Action, Google would transfer the execution to a phone.\n3. 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).\n4. Your service creates an *authorization code* and returns it to Google by redirecting the user's browser back to Google with the short-lived authorization code attached to the request.\n5. Google sends the authorization code to your token exchange endpoint, which verifies the authenticity of the code and returns an *access token* and a *refresh token*. The access token is a short-lived token that your service accepts as credentials to access APIs. The refresh token is a long-lived token that Google can store and use to acquire new access tokens when they expire.\n6. After the user has completed the account linking flow, every subsequent request sent from Assistant to your fulfillment webhook contains an access token.\n\nOAuth linking flows\n-------------------\n\nThis section goes over the various flows that can occur with OAuth linking.\n| **Note:** The following flows assume the user agrees to link their account with your service and grant Google permission to access their data with your API. If a user doesn't give consent, provide them a way to continue in your Action with an alternate, limited flow. For more information, see [Best practices](/assistant/identity/best-practices).\n\nEach flow contains these common steps after the user invokes your Action:\n\n| **Note:** A line from *Webhook* to *User* represents a [simple response](/assistant/conversational/prompts-simple) that you create and customize. Lines drawn from *Assistant* to *User* represent prompts that are owned by Assistant and have limited options for customization (requests that require permission are always owned by Assistant). From the user's perspective, both kinds of responses are delivered from Assistant.\n\nIn the flow above, you transition to the account linking system scene and provide\na customized rationale. Assistant asks the user if they want to link\ntheir account with your service and shows them a screen with the requested\npermissions. When the user consents, Google then redirects the user to your\nservice's authorization endpoint in the browser. The user signs in (or,\ndepending on your configuration, creates a new account) and grants your Action\npermission to access their data.\n\nThe flows after this point differ based on whether or not you implemented\nthe implicit flow or authorization code flow. These flows are described in\nthe following sections.\n\n### Flow 1: User signs in with implicit flow\n\n| **Note:** This diagram builds off of the **Common steps** diagram above.\n\nAfter the user logs in and their credentials are verified, your service creates\na long-lived access token and returns it to Google. At this point, the user's\nidentity in your Action is linked to the account they signed in with, and the\naccess token is attached to each API call Google makes to your service's APIs.\n\n### Flow 2: User signs in with authorization code flow\n\n| **Note:** This diagram builds off of the **Common steps** diagram above.\n\nAfter the user logs in and their credentials are verified, your service creates\nan authorization code and returns it to Google.\n\nThis authorization code is sent to your token exchange endpoint, which returns\nboth an access token and a refresh token. At this point, the user's identity\nin your Action is linked to whatever account they signed in with, and every\nsubsequent request sent from Assistant to your fulfillment contains an\naccess token."]]
