تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
يدعم نوع ربط حساب OAuth مسارين من مسارات OAuth 2.0 المتوافقة مع معايير الصناعة: المساران الضمني ورمز التفويض. خلال مسار الرمز الضمني، تفتح Google نقطة نهاية التفويض في متصفّح المستخدم. بعد تسجيل الدخول بنجاح،
تُرجع رمز دخول طويل الأمد إلى Google. بعد ذلك، يتم تضمين رمز الدخول هذا
في كل طلب يتم إرساله من "مساعد Google" إلى الإجراء الخاص بك.
بروتوكول OAuth هو الحل المقترَح لربط الحساب في حال انطباق ما يلي:
لديك تطبيق حالي لخادم OAuth 2.0 ولا يمكنك تمديد نقطة نهاية تبادل الرمز المميز لإضافة دعم لبروتوكولات Google من أجل الربط التلقائي وإنشاء الحساب من الرمز المميز للمعرّف (أي إضافة معلمتي
intent=get وintent=create في الطلبات إلى نقطة النهاية هذه).
للتأكّد من أنّ بروتوكول OAuth هو الحل المناسب لك، يُرجى الاطّلاع على صفحة
اختيار نوع ربط الحساب.
المصطلحات الرئيسية
قبل القراءة عن آلية عمل OAuth، تعرَّف على البنود التالية:
هدف المساعد في تسجيل الدخول إلى الحساب: هو هدف المساعد الذي تطلبه لطلب عملية ربط للحساب من "مساعد Google". لمزيد من المعلومات، اطّلع على
تسجيل الدخول إلى الحساب.
سلسلة السياق: سلسلة مخصّصة تضيفها إلى الغرض من مساعد
تسجيل الدخول إلى الحساب لإعلام المستخدم بسبب حاجته إلى ربط حسابه.
مسار رمز التفويض: خلال مسار 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.
يتضمّن كل مسار هذه الخطوات الشائعة بعد استدعاء المستخدم للإجراء الخاص بك:
في الخطوات أعلاه، يمكنك استدعاء هدف مساعد actions.intent.SIGN_IN لبدء عملية ربط الحساب. يسأل "مساعد Google" المستخدِم عمّا إذا كان يريد ربط حسابه بخدمتك ويعرض له شاشة بالأذونات المطلوبة. عندما يوافق المستخدم، ستعيد Google توجيه المستخدم إلى نقطة نهاية تفويض الخدمة في المتصفح. يسجّل المستخدم الدخول (أو ينشئ حسابًا جديدًا،
بناءً على عملية الضبط) ويمنح الإجراء
الإذن بالوصول إلى بياناته.
تختلف التدفقات بعد هذه النقطة اعتمادًا على ما إذا كنت قد نفذت
التدفق الضمني أو تدفق رمز التفويض أم لا. يتم وصف هذه التدفقات في
الأقسام التالية.
المسار 1: تسجيل دخول المستخدم من خلال تدفق ضمني
بعد تسجيل دخول المستخدم والتحقق من بيانات اعتماده، تنشئ الخدمة رمز دخول طويل الأمد وتعيده إلى Google. في هذه المرحلة، يتم ربط هوية المستخدم في الإجراء الخاص بك بالحساب الذي سجّل الدخول إليه، ويتم إرفاق رمز الدخول بكل طلب من استدعاءات Google لواجهات برمجة التطبيقات الخاصة بخدمتك.
المسار 2: تسجيل دخول المستخدم باستخدام مسار رمز التفويض
بعد تسجيل دخول المستخدم والتحقق من بيانات اعتماده، تنشئ الخدمة رمز تفويض وتعيده إلى Google.
يتم إرسال رمز التفويض هذا إلى نقطة نهاية تبادل الرمز المميّز، والتي تعرض كلاً من رمز الدخول ورمز إعادة التحميل. في هذه المرحلة، تكون هوية المستخدم في الإجراء الخاص بك مرتبطة بأي حساب سجّل الدخول إليه، ويحتوي كل طلب لاحق يتم إرساله من "مساعد Google" إلى تنفيذ الإجراء على رمز دخول.
تاريخ التعديل الأخير: 2025-07-26 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-07-26 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eOAuth account linking, utilizing OAuth 2.0 implicit or authorization code flows, securely connects users' Google accounts with your service.\u003c/p\u003e\n"],["\u003cp\u003eIn the implicit flow, a long-lived access token is returned directly upon successful login; whereas, the authorization code flow involves an intermediary code exchange for enhanced security.\u003c/p\u003e\n"],["\u003cp\u003eOAuth is recommended if you already use OAuth 2.0 and cannot adapt your token exchange endpoint for Google's automatic linking protocols.\u003c/p\u003e\n"],["\u003cp\u003eGoogle Assistant guides users through an account linking process, prompting for consent and redirecting to your authorization endpoint for sign-in and data access permission.\u003c/p\u003e\n"],["\u003cp\u003eAccess tokens, attached to subsequent requests, grant your service authorized access to user data, with refresh tokens ensuring continued access.\u003c/p\u003e\n"]]],[],null,["# OAuth concept guide (Dialogflow)\n\nThe OAuth account 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 the Assistant to your Action.\n\nOAuth 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 is the right solution for you, see the\n[Choose your account linking type](/assistant/df-asdk/identity/choose-type) page.\n\nKey terms\n---------\n\nBefore you read about how OAuth works, familiarize yourself with the following terms:\n\n- **Account sign-in helper intent:** A helper intent that you call to request an account linking flow from the Assistant. For more information, see [Account Sign-in](/assistant/df-asdk/helpers#account_sign-in).\n - **Context string:** A customized string that you add to the account sign-in helper intent that tells the user why you need them to link their account.\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 the 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 flows](#oauth_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 the 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 the Assistant to your fulfillment webhook contains an access token.\n\nOAuth flows\n-----------\n\nThis section goes over the various flows that can occur with OAuth.\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/df-asdk/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/df-asdk/simple-responses) that you create and customize. Lines drawn from *Assistant* to *User* represent prompts that are owned by the Assistant and have limited options for customization (requests that require permission are always owned by the Assistant). From the user's perspective, both kinds of responses are delivered from the Assistant.\n\nIn the flow above, you call the `actions.intent.SIGN_IN` helper intent to start\nthe account linking flow. The 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 the Assistant to your fulfillment contains an\naccess token."]]
