تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

استخدام OAuth 2.0 لتطبيقات خادم الويب

يوضّح هذا المستند كيفية استخدام تطبيقات خادم الويب لمكتبات عملاء Google API أو نقاط نهاية Google OAuth 2.0 لتنفيذ تفويض OAuth 2.0 للوصول إلى YouTube Data API.

يتيح بروتوكول OAuth 2.0 للمستخدمين مشاركة بيانات محدَّدة مع أحد التطبيقات والحفاظ على خصوصية أسماء المستخدمين وكلمات المرور والمعلومات الأخرى. على سبيل المثال، يمكن للتطبيق استخدام OAuth 2.0 للحصول على الإذن بتحميل الفيديوهات إلى قناة المستخدم على YouTube.

إنّ مسار OAuth 2.0 هذا مخصّص خصيصًا لتفويض المستخدم. وهو مصمّم للتطبيقات التي يمكنها تخزين المعلومات السرية والحفاظ على حالتها. يمكن لتطبيق خادم ويب حاصل على تفويض مناسب الوصول إلى واجهة برمجة تطبيقات أثناء تفاعل المستخدم مع التطبيق أو بعد مغادرة المستخدم للتطبيق.

غالبًا ما تستخدم تطبيقات خادم الويب أيضًا حسابات الخدمة لتفويض طلبات واجهة برمجة التطبيقات، لا سيما عند استدعاء واجهات برمجة تطبيقات Cloud للوصول إلى البيانات المستندة إلى المشروع بدلاً من البيانات الخاصة بالمستخدم. يمكن لتطبيقات خادم الويب استخدام حسابات الخدمة مع تفويض المستخدم. يُرجى العِلم أنّ YouTube Data API لا تتيح استخدام مسار حساب الخدمة إلا لأصحاب محتوى YouTube الذين يملكون قنوات متعدّدة على YouTube ويديرونها. على وجه التحديد، يمكن لمالكي المحتوى استخدام حسابات الخدمة لاستدعاء طرق واجهة برمجة التطبيقات التي تسمح باستخدام مَعلمة الطلب onBehalfOfContentOwner.

مكتبات العملاء

تستخدِم الأمثلة المتعلّقة بلغة معيّنة في هذه الصفحة مكتبات عملاء Google API لتنفيذ عملية تفويض OAuth 2.0. لتنفيذ نماذج الرموز البرمجية، عليك أولاً تثبيت مكتبة العميل بلغتك.

عند استخدام مكتبة عملاء Google API لمعالجة مسار OAuth 2.0 في تطبيقك، تُنفِّذ مكتبة العميل العديد من الإجراءات التي كان على التطبيق معالجتها بمفرده. على سبيل المثال، يحدِّد هذا الإطار الزمني الحالات التي يمكن فيها للتطبيق استخدام رموز الوصول المخزَّنة أو إعادة تحميلها، وكذلك الحالات التي يجب فيها على التطبيق إعادة الحصول على الموافقة. تُنشئ مكتبة العميل أيضًا عناوين URL مختصرة صحيحة وتساعد في تنفيذ معالجات إعادة التوجيه التي تتبادل رموز التفويض برموز الوصول.

تتوفّر مكتبات عملاء Google API للتطبيقات من جهة الخادم باللغات التالية:

المتطلبات الأساسية

تفعيل واجهات برمجة التطبيقات لمشروعك

يجب أن يفعّل أي تطبيق يستدعي Google APIs واجهات برمجة التطبيقات هذه في .

لتفعيل واجهة برمجة تطبيقات لمشروعك، اتّبِع الخطوات التالية:

في .
استخدِم صفحة المكتبة للعثور على YouTube Data API وتفعيلها. ابحث عن أي واجهات برمجة تطبيقات أخرى سيستخدمها تطبيقك وفعِّلها أيضًا.

إنشاء بيانات اعتماد التفويض

يجب أن يكون لدى أي تطبيق يستخدم بروتوكول OAuth 2.0 للوصول إلى Google APIs بيانات اعتماد تفويض تُعرّف التطبيق لخادم OAuth 2.0 في Google. توضّح الخطوات التالية كيفية إنشاء بيانات اعتماد لمشروعك. ويمكن بعد ذلك لتطبيقاتك استخدام بيانات الاعتماد للوصول إلى واجهات برمجة التطبيقات التي فعّلتها لهذا المشروع.

انقر على إنشاء بيانات اعتماد > معرِّف عميل OAuth.
اختَر نوع التطبيق تطبيق الويب.
املأ النموذج وانقر على إنشاء. يجب أن تحدِّد التطبيقات التي تستخدم لغات وأطر عمل مثل PHP وJava وPython وRuby و .NET معرّفات الموارد المنتظمة (URI) لإعادة التوجيه المعتمَدة. معرّفات الموارد المنتظمة لإعادة التوجيه هي نقاط النهاية التي يمكن لخادم OAuth 2.0 إرسال الردود إليها. يجب أن تلتزم نقاط النهاية هذه بقواعد التحقّق من Google.
للاختبار، يمكنك تحديد عناوين URL تشير إلى الجهاز المحلي، مثل http://localhost:8080. مع وضع ذلك في الاعتبار، يُرجى العلم أنّ جميع الأمثلة الواردة في هذا المستند تستخدِم http://localhost:8080 كمعرّف الموارد المنتظم لإعادة التوجيه.

ننصحك بتصميم نقاط نهاية المصادقة في تطبيقك لكي لا يعرِض تطبيقك رموز التفويض لموارد أخرى في الصفحة.

بعد إنشاء بيانات الاعتماد، نزِّل ملف client_secret.json من . احفظ الملف بأمان في مكان يمكن لتطبيقك فقط الوصول إليه.

تحديد نطاقات الوصول

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

قبل بدء تنفيذ عملية التفويض باستخدام بروتوكول OAuth 2.0، ننصحك بتحديد النطاقات التي سيحتاج تطبيقك إلى إذن للوصول إليها.

ننصح أيضًا بأن يطلب تطبيقك الوصول إلى نطاقات التفويض من خلال عملية تفويض متزايد، يطلب فيها تطبيقك الوصول إلى بيانات المستخدم في سياق استخدام التطبيق. تساعد هذه أفضل الممارسات المستخدمين على فهم سبب احتياج تطبيقك إلى الأذونات التي يطلبها بسهولة أكبر.

يستخدم الإصدار 3 من YouTube Data API النطاقات التالية:

المناظير
https://www.googleapis.com/auth/youtube	إدارة حسابك في YouTube
https://www.googleapis.com/auth/youtube.channel-memberships.creator	الاطّلاع على قائمة بأعضاء القناة النشطين حاليًا ومستواهم الحالي وتاريخ انضمامهم
https://www.googleapis.com/auth/youtube.force-ssl	الاطّلاع على فيديوهاتك على YouTube وتقييماتها وتعليقاتها وترجماتها وكذلك تعديلها وحذفها نهائيًا
https://www.googleapis.com/auth/youtube.readonly	عرض حسابك في YouTube
https://www.googleapis.com/auth/youtube.upload	إدارة فيديوهات YouTube
https://www.googleapis.com/auth/youtubepartner	عرض وإدارة أصولك والمحتوى المرتبط بها على YouTube
https://www.googleapis.com/auth/youtubepartner-channel-audit	عرض معلومات خاصة عن قناتك على YouTube ذات صلة أثناء عملية تدقيق شريك YouTube

يحتوي مستند نطاقات واجهة برمجة التطبيقات OAuth 2.0 على قائمة كاملة بالنطاقات التي يمكنك استخدامها للوصول إلى Google APIs.

المتطلبات الخاصة باللغة

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

PHP

لتشغيل نماذج رموز PHP في هذا المستند، ستحتاج إلى ما يلي:

‫PHP 8.0 أو إصدار أحدث مع تثبيت واجهة سطر الأوامر (CLI) وإضافة JSON
أداة إدارة التبعية في Composer
مكتبة برامج Google APIs للغة PHP:
```
composer require google/apiclient:^2.15.0
```

اطّلِع على مكتبة برامج Google APIs ل PHP للحصول على مزيد من المعلومات.

Python

لتشغيل عيّنات رموز Python في هذا المستند، ستحتاج إلى ما يلي:

الإصدار 3.7 من Python أو إصدار أحدث
أداة إدارة الحِزم pip
إصدار 2.0 من مكتبة برامج Google APIs للغة Python:
```
pip install --upgrade google-api-python-client
```
‫google-auth وgoogle-auth-oauthlib و google-auth-httplib2 لتفويض المستخدم
```
pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2
```
إطار عمل تطبيق الويب Flask Python
```
pip install --upgrade flask
```
مكتبة requests HTTP
```
pip install --upgrade requests
```

راجِع ملاحظة الإصدار لمكتبة Python برمجة التطبيقات من Google إذا لم تتمكّن من ترقية Python ودليل نقل البيانات المرتبط بها.

Ruby

لتشغيل نماذج رموز Ruby في هذا المستند، ستحتاج إلى ما يلي:

الإصدار 2.6 من Ruby أو إصدار أحدث
مكتبة Google Auth Library للغة Ruby:
```
gem install googleauth
```
إطار عمل تطبيق الويب Sinatra Ruby
```
gem install sinatra
```

Node.js

لتنفيذ نماذج رموز Node.js البرمجية في هذا المستند، ستحتاج إلى ما يلي:

إصدار LTS في مرحلة الصيانة أو إصدار LTS النشط أو الإصدار الحالي من Node.js

عميل Google APIs لنظام Node.js:

npm install googleapis crypto express express-session

HTTP/REST

لست بحاجة إلى تثبيت أي مكتبات لتتمكّن من طلب نقاط نهاية OAuth 2.0 مباشرةً.

الحصول على رموز دخول OAuth 2.0

توضِّح الخطوات التالية كيفية تفاعل تطبيقك مع خادم OAuth 2.0 من Google للحصول على موافقة المستخدم لتنفيذ طلب واجهة برمجة التطبيقات بالنيابة عنه. يجب أن يحصل تطبيقك على هذه الموافقة قبل أن يتمكّن من تنفيذ طلب Google API الذي يتطلّب تفويض المستخدم.

في ما يلي قائمة تلخِّص هذه الخطوات بسرعة:

يحدِّد تطبيقك الأذونات التي يحتاج إليها.
يعيد تطبيقك توجيه المستخدم إلى Google مع قائمة الأذونات المطلوبة.
يقرر المستخدم ما إذا كان سيمنح أذونات تطبيقك.
يتعرّف تطبيقك على القرار الذي اتخذه المستخدم.
إذا منح المستخدم الأذونات المطلوبة، يسترجع تطبيقك الرموز المميّزة اللازمة للقيام بطلبات واجهة برمجة التطبيقات نيابةً عن المستخدم.

الخطوة 1: ضبط مَعلمات التفويض

الخطوة الأولى هي إنشاء طلب التفويض. يحدِّد هذا الطلب مَعلمات تحدد تطبيقك وتحدِّد الأذونات التي سيُطلب من المستخدم منحها لتطبيقك.

إذا كنت تستخدم مكتبة عملاء Google لمصادقة OAuth 2.0 وتفويضها، عليك إنشاء عنصر يحدِّد هذه المَعلمات وضبطه.
في حال طلب نقطة نهاية Google OAuth 2.0 مباشرةً، ستُنشئ عنوان URL وتضبط المَعلمات على عنوان URL هذا.

تحدِّد علامات التبويب أدناه مَعلمات التفويض المتوافقة لتطبيقات خادم الويب. توضِّح المثالان التاليان المخصّصان للغة أيضًا كيفية استخدام مكتبة عملاء أو مكتبة تفويض لضبط عنصر يضبط هذه المَعلمات.

PHP

ينشئ مقتطف الرمز البرمجي التالي عنصرًا من النوع Google\Client()، والذي يحدِّد المَعلمات في طلب التفويض.

يستخدم هذا الكائن معلومات من ملف client_secret.json لتحديد تطبيقك. (اطّلِع على إنشاء بيانات اعتماد التفويض للحصول على مزيد من المعلومات عن هذا الملف). ويحدِّد العنصر أيضًا النطاقات التي يطلب تطبيقك إذنًا بالوصول إليها وعنوان URL لنقطة نهاية مصادقة تطبيقك، والتي ستعالج الردّ من خادم Google OAuth 2.0. أخيرًا، يضبط الرمز المَعلمتَين access_type و include_granted_scopes الاختياريتين.

على سبيل المثال، يطلب هذا الرمز الوصول بلا إنترنت لإدارة حساب أحد المستخدمين على YouTube:

use Google\Client;

$client = new Client();

// Required, call the setAuthConfig function to load authorization credentials from
// client_secret.json file.
$client->setAuthConfig('client_secret.json');

// Required, to set the scope value, call the addScope function
$client->addScope(GOOGLE_SERVICE_YOUTUBE::YOUTUBE_FORCE_SSL);

// Required, call the setRedirectUri function to specify a valid redirect URI for the
// provided client_id
$client->setRedirectUri('http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php');

// Recommended, offline access will give you both an access and refresh token so that
// your app can refresh the access token without user interaction.
$client->setAccessType('offline');

// Recommended, call the setState function. Using a state value can increase your assurance that
// an incoming connection is the result of an authentication request.
$client->setState($sample_passthrough_value);

// Optional, if your application knows which user is trying to authenticate, it can use this
// parameter to provide a hint to the Google Authentication Server.
$client->setLoginHint('hint@example.com');

// Optional, call the setPrompt function to set "consent" will prompt the user for consent
$client->setPrompt('consent');

// Optional, call the setIncludeGrantedScopes function with true to enable incremental
// authorization
$client->setIncludeGrantedScopes(true);

Python

يستخدم مقتطف الرمز البرمجي التالي وحدة google-auth-oauthlib.flow لإنشاء طلب التفويض.

ينشئ الرمز عنصرًا من النوع Flow، والذي يحدِّد تطبيقك باستخدام معلومات من ملف client_secret.json الذي نزّلته بعد إنشاء بيانات اعتماد التفويض. ويحدِّد هذا العنصر أيضًا النطاقات التي يطلب تطبيقك إذن الوصول إليها وعنوان URL لنقطة نهاية المصادقة في تطبيقك، والتي ستعالج الاستجابة الواردة من خادم OAuth 2.0 في Google. أخيرًا، يضبط الرمز البرمجي المَعلمتَين access_type وinclude_granted_scopes الاختياريتين.

على سبيل المثال، يطلب هذا الرمز الوصول بلا إنترنت لإدارة حساب أحد المستخدمين على YouTube:

import google.oauth2.credentials
import google_auth_oauthlib.flow

# Required, call the from_client_secrets_file method to retrieve the client ID from a
# client_secret.json file. The client ID (from that file) and access scopes are required. (You can
# also use the from_client_config method, which passes the client configuration as it originally
# appeared in a client secrets file but doesn't access the file itself.)
flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file('client_secret.json',
    scopes=['https://www.googleapis.com/auth/youtube.force-ssl'])

# Required, indicate where the API server will redirect the user after the user completes
# the authorization flow. The redirect URI is required. The value must exactly
# match one of the authorized redirect URIs for the OAuth 2.0 client, which you
# configured in the API Console. If this value doesn't match an authorized URI,
# you will get a 'redirect_uri_mismatch' error.
flow.redirect_uri = 'https://www.example.com/oauth2callback'

# Generate URL for request to Google's OAuth 2.0 server.
# Use kwargs to set optional request parameters.
authorization_url, state = flow.authorization_url(
    # Recommended, enable offline access so that you can refresh an access token without
    # re-prompting the user for permission. Recommended for web server apps.
    access_type='offline',
    # Optional, enable incremental authorization. Recommended as a best practice.
    include_granted_scopes='true',
    # Optional, if your application knows which user is trying to authenticate, it can use this
    # parameter to provide a hint to the Google Authentication Server.
    login_hint='hint@example.com',
    # Optional, set prompt to 'consent' will prompt the user for consent
    prompt='consent')

Ruby

استخدِم ملف client_secrets.json الذي أنشأته لضبط عنصر عميل في تطبيقك. عند ضبط عنصر عميل، يمكنك تحديد النطاقات التي يحتاج تطبيقك إلى الوصول إليها، بالإضافة إلى عنوان URL لنقطة نهاية المصادقة في تطبيقك، والتي ستعالج الاستجابة من خادم OAuth 2.0.

على سبيل المثال، يطلب هذا الرمز الوصول بلا إنترنت لإدارة حساب أحد المستخدمين على YouTube:

require 'googleauth'
require 'googleauth/web_user_authorizer'
require 'googleauth/stores/redis_token_store'

require 'google/apis/youtube_v3'

# Required, call the from_file method to retrieve the client ID from a
# client_secret.json file.
client_id = Google::Auth::ClientId.from_file('/path/to/client_secret.json')

# Required, scope value 
scope = 'https://www.googleapis.com/auth/youtube.force-ssl'

# Required, Authorizers require a storage instance to manage long term persistence of
# access and refresh tokens.
token_store = Google::Auth::Stores::RedisTokenStore.new(redis: Redis.new)

# Required, indicate where the API server will redirect the user after the user completes
# the authorization flow. The redirect URI is required. The value must exactly
# match one of the authorized redirect URIs for the OAuth 2.0 client, which you
# configured in the API Console. If this value doesn't match an authorized URI,
# you will get a 'redirect_uri_mismatch' error.
callback_uri = '/oauth2callback'

# To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI
# from the client_secret.json file. To get these credentials for your application, visit
# https://console.cloud.google.com/apis/credentials.
authorizer = Google::Auth::WebUserAuthorizer.new(client_id, scope,
                                                token_store, callback_uri)

يستخدم تطبيقك عنصر العميل لتنفيذ عمليات OAuth 2.0، مثل إنشاء عناوين URL لطلبات التفويض وتطبيق الرموز المميّزة للوصول إلى طلبات HTTP.

Node.js

ينشئ مقتطف الرمز البرمجي التالي عنصرًا من النوع google.auth.OAuth2، والذي يحدِّد المَعلمات في طلب التفويض.

يستخدم هذا الكائن معلومات من ملف client_secret.json لتحديد تطبيقك. لطلب أذونات من المستخدم لاسترداد رمز دخول، يمكنك إعادة توجيهه إلى صفحة موافقة. لإنشاء عنوان URL لصفحة الموافقة:

const {google} = require('googleapis');
const crypto = require('crypto');
const express = require('express');
const session = require('express-session');

/**
 * To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI
 * from the client_secret.json file. To get these credentials for your application, visit
 * https://console.cloud.google.com/apis/credentials.
 */
const oauth2Client = new google.auth.OAuth2(
  YOUR_CLIENT_ID,
  YOUR_CLIENT_SECRET,
  YOUR_REDIRECT_URL
);

// Access scopes for YouTube API
const scopes = [
  'https://www.googleapis.com/auth/youtube.force-ssl'
];

// Generate a secure random state value.
const state = crypto.randomBytes(32).toString('hex');

// Store state in the session
req.session.state = state;

// Generate a url that asks permissions for the Drive activity and Google Calendar scope
const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined above.
    * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as a best practice.
  include_granted_scopes: true,
  // Include the state parameter to reduce the risk of CSRF attacks.
  state: state
});

ملاحظة مهمة: لا يتم عرض refresh_token إلا في عملية التفويض الأولى. يمكنك الاطّلاع على المزيد من التفاصيل هنا.

HTTP/REST

يمكنك العثور على نقطة نهاية OAuth 2.0 في Google على الرابط https://accounts.google.com/o/oauth2/v2/auth. لا يمكن الوصول إلى نقطة النهاية هذه إلا من خلال بروتوكول HTTPS. يتم رفض اتصالات HTTP العادية.

يتيح خادم التفويض في Google مَعلمات سلسلة الطلب التالية لتطبيقات خادم الويب:

المعلمات

client_id

مطلوب

معرّف العميل لتطبيقك. يمكنك العثور على هذه القيمة في .

redirect_uri

مطلوب

لتحديد المكان الذي يعيد فيه خادم واجهة برمجة التطبيقات توجيه المستخدم بعد إكماله عملية التفويض. يجب أن تتطابق القيمة تمامًا مع أحد عناوين URL المعتمَدة لإعادة التوجيه لملف تعريف العميل في OAuth 2.0، والذي أعددته في العميل. إذا لم تتطابق هذه القيمة مع عنوان URL مُعتمَد لإعادة التوجيه للclient_id المقدَّمة، ستظهر لك رسالة خطأ redirect_uri_mismatch.

يُرجى العلم أنّه يجب أن يتطابق كلّ من مخطّط http أو https وحالة الأحرف والشرطة المائلة المتّبعة (/).

response_type

مطلوب

لتحديد ما إذا كانت نقطة نهاية Google OAuth 2.0 تعرض رمز تفويض.

اضبط قيمة المَعلمة على code لتطبيقات خادم الويب.

scope

مطلوب

قائمة مفصولة بالفواصل بالنطاقات التي تحدِّد الموارد التي يمكن لتطبيقك الوصول إليها نيابةً عن المستخدم وتُستخدَم هذه القيم لعرض شاشة الموافقة التي تعرِضها Google للمستخدم.

تتيح النطاقات لتطبيقك طلب الوصول إلى الموارد التي يحتاج إليها فقط، مع السماح للمستخدمين أيضًا بالتحكم في مقدار الوصول الذي يمنحه لتطبيقك. وبالتالي، هناك علاقة عكسية بين عدد النطاقات المطلوبة واحتمالية الحصول على موافقة المستخدم.

يستخدم الإصدار 3 من YouTube Data API النطاقات التالية:

المناظير
https://www.googleapis.com/auth/youtube	إدارة حسابك في YouTube
https://www.googleapis.com/auth/youtube.channel-memberships.creator	الاطّلاع على قائمة بأعضاء القناة النشطين حاليًا ومستواهم الحالي وتاريخ انضمامهم
https://www.googleapis.com/auth/youtube.force-ssl	الاطّلاع على فيديوهاتك على YouTube وتقييماتها وتعليقاتها وترجماتها وكذلك تعديلها وحذفها نهائيًا
https://www.googleapis.com/auth/youtube.readonly	عرض حسابك في YouTube
https://www.googleapis.com/auth/youtube.upload	إدارة فيديوهات YouTube
https://www.googleapis.com/auth/youtubepartner	عرض وإدارة أصولك والمحتوى المرتبط بها على YouTube
https://www.googleapis.com/auth/youtubepartner-channel-audit	عرض معلومات خاصة عن قناتك على YouTube ذات صلة أثناء عملية تدقيق شريك YouTube

يقدّم مستند نطاقات واجهة برمجة التطبيقات OAuth 2.0 قائمة كاملة بالنطاقات التي يمكنك استخدامها للوصول إلى Google APIs.

ننصحك بأن يطلب تطبيقك الوصول إلى نطاقات التفويض في السياق كلما أمكن ذلك. من خلال طلب الوصول إلى بيانات المستخدمين في السياق، من خلال المصادقة المتزايدة، يمكنك مساعدة المستخدمين على فهم سبب احتياج تطبيقك إلى إذن الوصول الذي يطلبه بسهولة أكبر.

access_type

مقترَح

تشير هذه السمة إلى ما إذا كان بإمكان تطبيقك إعادة تحميل الرموز المميّزة للوصول عندما لا يكون المستخدم في المتصفّح. قيم المَعلمات الصالحة هي online، وهي القيمة التلقائية وoffline.

اضبط القيمة على offline إذا كان تطبيقك بحاجة إلى إعادة تحميل رموز الوصول عندما لا يكون المستخدم متصلاً بالمتصفّح. هذه هي طريقة إعادة تحميل رموز الدخول الموضّحة لاحقًا في هذا المستند. تُوجّه هذه القيمة خادم مصادقة Google لإرجاع رمز مميز لإعادة التحميل ورمز دخول في المرة الأولى التي يتبادل فيها تطبيقك رمز التفويض بالرموز المميزة.

state

مقترَح

تحدِّد أي قيمة سلسلة يستخدمها تطبيقك للحفاظ على الحالة بين طلب التفويض واستجابة خادم التفويض. يعرض الخادم القيمة الدقيقة التي ترسلها كزوج name=value في مكوّن طلب البحث عن عنوان URL (?) من redirect_uri بعد أن يوافق المستخدم على طلب الوصول إلى تطبيقك أو يرفضه.

يمكنك استخدام هذه المَعلمة لعدة أغراض، مثل توجيه المستخدِم إلى المرجع الصحيح في تطبيقك وإرسال قيم عشوائية وتجنُّب التزوير لطلبات المواقع الإلكترونية المختلفة. بما أنّه يمكن تخمين redirect_uri، يمكن أن يؤدي استخدام قيمة state إلى زيادة ثقتك بأنّ الاتصال الوافد هو نتيجة طلب مصادقة. إذا أنشأت سلسلة عشوائية أو شفّرت تجزئة ملف تعريف ارتباط أو قيمة أخرى تُسجّل حالة العميل، يمكنك التحقّق من الاستجابة لتأكيد أنّ الطلب والاستجابة قد نشأا من المتصفّح نفسه، ما يوفر حماية من الهجمات، مثل تزييف الطلبات على مستوى مواقع إلكترونية مختلفة. اطّلِع على مستندات OpenID Connect للحصول على مثال على كيفية إنشاء رمز state وتأكيده.

ملاحظة مهمة: يجب أن يمنع عميل OAuth هجمات CSRF كما هو موضّح في مواصفات OAuth2 . وإحدى الطرق لتحقيق ذلك هي استخدام المَعلمة state للحفاظ على الحالة بين طلب التفويض وردّ خادم التفويض.

include_granted_scopes

اختياريّ

تتيح للتطبيقات استخدام المصادقة المتزايدة لطلب الوصول إلى نطاقات إضافية في السياق. في حال ضبط قيمة هذه المَعلمة على true ومنح طلب التفويض، سيشمل رمز الوصول الجديد أيضًا أي نطاقات منح المستخدم للتطبيق إذن الوصول إليها في السابق. راجِع القسم التفويض المتزايد للاطّلاع على أمثلة.

enable_granular_consent

اختياريّ

الإعداد التلقائي هو true. في حال ضبط القيمة على false، سيتم إيقاف أذونات حساب Google الأكثر دقة لمعرّفات عملاء OAuth التي تم إنشاؤها قبل عام 2019. لن يكون هناك أي تأثير على معرِّفات عملاء OAuth الأحدث، لأنّه يتم دائمًا تفعيل أذونات أكثر دقة لها.

وعندما تفعّل Google أذونات دقيقة لتطبيق معيّن، لن تعود هذه المَعلمة تُحدث أثرًا.

login_hint

اختياريّ

إذا كان تطبيقك يعرف المستخدم الذي يحاول المصادقة، يمكنه استخدام هذه المَعلمة لتقديم تلميح إلى خادم مصادقة Google. يستخدم الخادم التلميح لمحاولة تبسيط عملية تسجيل الدخول إما عن طريق ملء حقل البريد الإلكتروني مسبقًا في نموذج تسجيل الدخول أو عن طريق اختيار جلسة تسجيل الدخول المتعدّد المناسبة.

اضبط قيمة المَعلمة على عنوان بريد إلكتروني أو معرّف sub، وهو معادل لرقم تعريف المستخدم على Google.

prompt

اختياريّ

قائمة بطلبات عرض المستخدم، مفصولة بمسافات وحساسة لحالة الأحرف في حال عدم تحديد هذه المَعلمة، لن يُطلَب من المستخدم منح الإذن إلا في المرة الأولى التي يطلب فيها مشروعك الوصول إلى البيانات. يمكنك الاطّلاع على طلب إعادة الموافقة للحصول على مزيد من المعلومات.

القيم المحتملة هي:

`none`	لا تعرِض أي شاشات مصادقة أو موافقة. يجب عدم تحديدها باستخدام قيم أخرى.
`consent`	اطلب من المستخدم الموافقة.
`select_account`	اطلب من المستخدم اختيار حساب.

الخطوة 2: إعادة التوجيه إلى خادم OAuth 2.0 من Google

إعادة توجيه المستخدم إلى خادم OAuth 2.0 من Google لبدء عملية المصادقة والتفويض يحدث ذلك عادةً عندما يحتاج تطبيقك أولاً إلى الوصول إلى بيانات المستخدم. في حال المصادقة المتزايدة، تحدث هذه الخطوة أيضًا عندما يحتاج تطبيقك أولاً إلى الوصول إلى موارد إضافية ليس لديه إذن بالوصول إليها بعد.

PHP

أنشئ عنوان URL لطلب الوصول من خادم OAuth 2.0 في Google:
```
$auth_url = $client->createAuthUrl();
```

إعادة توجيه المستخدم إلى $auth_url:

header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL));

Python

يوضّح هذا المثال كيفية إعادة توجيه المستخدم إلى عنوان URL الخاص بالتفويض باستخدام إطار عمل تطبيق الويب Flask:

return flask.redirect(authorization_url)

Ruby

أنشئ عنوان URL لطلب الوصول من خادم OAuth 2.0 في Google:
```
auth_uri = authorizer.get_authorization_url(request: request)
```
أعِد توجيه المستخدم إلى auth_uri.

Node.js

استخدِم عنوان URL الذي تم إنشاؤه authorizationUrl من الخطوة 1 generateAuthUrl لطلب الوصول من خادم OAuth 2.0 في Google.
أعِد توجيه المستخدم إلى authorizationUrl.
```
res.redirect(authorizationUrl);
```

HTTP/REST

نموذج إعادة توجيه إلى خادم التفويض في Google

يطلب نموذج عنوان URL أدناه الوصول بلا إنترنت (access_type=offline) إلى نطاق يسمح بالوصول لعرض حساب المستخدم على YouTube. ويستخدم هذا الإجراء تفويضًا متزايدًا لضمان أن يشمل رمز الوصول الجديد أي نطاقات منحها المستخدم سابقًا للتطبيق. يحدّد عنوان URL أيضًا قيمًا للمَعلمات المطلوبة redirect_uri وresponse_type و client_id بالإضافة إلى المَعلمة state. يحتوي عنوان URL على فواصل أسطر ومسافات لتسهيل القراءة.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 access_type=offline&
 include_granted_scopes=true&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 response_type=code&
 client_id=client_id

بعد إنشاء عنوان URL للطلب، أعِد توجيه المستخدم إليه.

يُجري خادم OAuth 2.0 من Google مصادقة المستخدم ويحصل على موافقته على منح تطبيقك إذن الوصول إلى النطاقات المطلوبة. يتم إرسال الاستجابة مرة أخرى إلى تطبيقك باستخدام عنوان URL لإعادة التوجيه الذي حدّدته.

الخطوة 3: تطلب Google من المستخدم الموافقة

في هذه الخطوة، يقرّر المستخدم ما إذا كان سيمنح تطبيقك الإذن بالوصول المطلوب. في هذه المرحلة، تعرض Google نافذة موافقة تعرض اسم تطبيقك وخدمات Google API التي يُطلب إذن الوصول إليها باستخدام بيانات اعتماد التفويض الخاصة بالمستخدم، بالإضافة إلى ملخّص لنطاقات الوصول التي سيتم منحها. يمكن للمستخدم عندئذٍ الموافقة على منح إذن الوصول إلى نطاق واحد أو أكثر من النطاقات التي يطلبها تطبيقك أو رفض الطلب.

لا يحتاج تطبيقك إلى اتّخاذ أي إجراء في هذه المرحلة أثناء انتظاره للردّ من خادم OAuth 2.0 في Google الذي يشير إلى ما إذا تم منح أي إذن وصول. يتم شرح هذا الردّ في الخطوة التالية.

الأخطاء

قد تعرض الطلبات المرسَلة إلى نقطة نهاية التفويض في OAuth 2.0 من Google رسائل خطأ موجَّهة للمستخدمين بدلاً من عمليات المصادقة والتفويض المتوقّعة. في ما يلي رموز الأخطاء الشائعة والحلول المقترَحة لها.

`admin_policy_enforced`

لا يمكن لحساب Google تفويض نطاق واحد أو أكثر من النطاقات المطلوبة بسبب سياسات مشرف Google Workspace. راجِع مقالة مساعدة مشرفي Google Workspace التحكّم في اختيار التطبيقات التابعة لجهات خارجية والتطبيقات الداخلية التي يمكنها الوصول إلى بيانات Google Workspace للحصول على مزيد من المعلومات عن كيفية حظر المشرف للوصول إلى جميع النطاقات أو النطاقات الحسّاسة والمشروطة إلى أن يتم منح إذن الوصول صراحةً إلى معرّف عميل OAuth.

`disallowed_useragent`

يتم عرض نقطة نهاية التفويض داخل وكيل مستخدم مضمّن غير مسموح به من قِبل سياسات OAuth 2.0 في Google.

Android

قد تظهر رسالة الخطأ هذه لمطوّري تطبيقات Android عند فتح طلبات التفويض في android.webkit.WebView. على المطوّرين استخدام مكتبات Android بدلاً من ذلك، مثل تسجيل الدخول باستخدام حساب Google على Android أو AppAuth لنظام التشغيل Android من OpenID Foundation.

قد يواجه مطوّرو الويب هذا الخطأ عندما يفتح تطبيق Android رابط ويب عامًا في وكيل مستخدم مضمّن وينتقل مستخدم إلى نقطة نهاية التفويض في بروتوكول OAuth 2.0 من Google من موقعك الإلكتروني. على المطوّرين السماح بفتح الروابط العامة في معالِج الروابط التلقائي لنظام التشغيل، والذي يتضمّن معالِجَي روابط تطبيقات Android أو تطبيق المتصفّح التلقائي. وتعدّ مكتبة علامات التبويب المخصّصة لنظام التشغيل Android خيارًا متوافقًا أيضًا.

iOS

قد يواجه مطوّرو التطبيقات على نظامَي التشغيل iOS وmacOS هذا الخطأ عند فتح طلبات التفويض في WKWebView. على المطوّرين بدلاً من ذلك استخدام مكتبات iOS، مثل Google Sign-In لنظام التشغيل iOS أو AppAuth لنظام التشغيل iOS من OpenID Foundation.

قد يواجه مطوّرو الويب هذا الخطأ عندما يفتح تطبيق iOS أو macOS رابط ويب عامًا في وكيل مستخدم مضمّن وينتقل مستخدم إلى نقطة نهاية التفويض باستخدام بروتوكول OAuth 2.0 من Google من موقعك الإلكتروني. على المطوّرين السماح بفتح الروابط العامة في معالِج الروابط التلقائي لنظام التشغيل، والذي يشمل معالِجي الروابط العامة أو تطبيق المتصفّح التلقائي. وتعدّ مكتبة SFSafariViewController أيضًا خيارًا متوافقًا.

`org_internal`

معرّف عميل OAuth في الطلب هو جزء من مشروع يحدّ من الوصول إلى حسابات Google في مؤسسة Google Cloud معيّنة. لمزيد من المعلومات حول خيار الضبط هذا، يُرجى الاطّلاع على القسم نوع المستخدم في مقالة المساعدة حول إعداد شاشة موافقة بروتوكول OAuth.

`invalid_client`

سر عميل OAuth غير صحيح. راجِع إعدادات عميل OAuth، بما في ذلك معرّف العميل وسرّه المستخدَمَين لهذا الطلب.

`invalid_grant`

عند إعادة تحميل رمز مميّز للوصول أو استخدام التفويض المتزايد، قد تكون صلاحية الرمز المميّز قد انتهت أو تم إبطالها. مصادقة المستخدم مرة أخرى وطلب موافقة المستخدم للحصول على الرموز الجديدة إذا استمر ظهور هذا الخطأ، تأكَّد من أنّه تم ضبط إعدادات تطبيقك بشكل صحيح وأنّك تستخدِم الرموز المميّزة والمَعلمات الصحيحة في طلبك. بخلاف ذلك، قد يكون حساب المستخدم قد تم حذفه أو إيقافه.

`redirect_uri_mismatch`

لا يتطابق redirect_uri الذي تم تمريره في طلب التفويض مع معرّف موارد منتظم (URI) لإعادة توجيه مفوَّض لمعرّف عميل OAuth. راجِع معرّفات الموارد المنتظمة (URI) المعتمَدة لإعادة التوجيه في .

قد تشير المَعلمة redirect_uri إلى عملية OAuth خارج النطاق (OOB) التي تم إيقافها نهائيًا ولم تعُد متاحة. يُرجى الرجوع إلى دليل نقل البيانات لتعديل عملية دمج حسابك.

`invalid_request`

حدث خطأ في الطلب الذي قدّمته. قد يرجع ذلك إلى عدد من الأسباب:

لم يتم تنسيق الطلب بشكل صحيح.
عدم توفّر المَعلمات المطلوبة في الطلب
يستخدم الطلب طريقة تفويض لا تتوافق مع Google. التأكّد من أنّ عملية دمج OAuth تستخدم طريقة دمج مقترَحة

الخطوة 4: معالجة استجابة خادم OAuth 2.0

ملاحظة مهمة: قبل معالجة استجابة OAuth 2.0 على الخادم، عليك التأكّد من أنّ state المستلَم من Google يتطابق مع state المُرسَل في طلب التفويض. يساعد هذا التحقّق في التأكّد من أنّ المستخدم هو من يقدّم الطلب وليس أحد النصوص البرمجية الضارّة، كما يساعد في الحدّ من خطر هجمات CSRF.

يستجيب خادم OAuth 2.0 لطلب الوصول الذي قدّمه تطبيقك باستخدام عنوان URL المحدّد في الطلب.

إذا وافق المستخدم على طلب الوصول، سيتضمّن الردّ رمز تفويض. إذا لم يوافق المستخدم على الطلب، سيتضمّن الردّ رسالة خطأ. يظهر رمز التفويض أو رسالة الخطأ التي يتم عرضها على خادم الويب في سلسلة طلب البحث ، كما هو موضّح أدناه:

استجابة خطأ:

https://oauth2.example.com/auth?error=access_denied

استجابة رمز التفويض:

https://oauth2.example.com/auth?code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7

ملاحظة مهمة: إذا كانت نقطة نهاية الاستجابة تعرِض صفحة HTML، سيتمكّن أيّ موارد في تلك الصفحة من الاطّلاع على رمز التفويض في عنوان URL. يمكن للنصوص البرمجية قراءة عنوان URL مباشرةً، وقد يتم إرسال عنوان URL في عنوان HTTP Referer إلى أيّ من الموارد أو جميعها في الصفحة.

فكِّر جيدًا في ما إذا كنت تريد إرسال بيانات اعتماد التفويض إلى جميع الموارد في هذه الصفحة (خاصة النصوص البرمجية التابعة لجهات خارجية، مثل المكوّنات الإضافية للشبكات الاجتماعية وأدوات الإحصاءات). لتجنُّب حدوث هذه المشكلة، ننصحك بأن يعالج الخادم الطلب أولاً، ثم يعيد التوجيه إلى عنوان URL آخر لا يتضمّن مَعلمات الاستجابة.

نموذج استجابة خادم OAuth 2.0

يمكنك اختبار هذه العملية من خلال النقر على نموذج عنوان URL التالي الذي يطلب فسحة وصول قراءة فقط لعرض البيانات الوصفية للملفات في Google Drive وفسحة وصول قراءة فقط لعرض أحداث "تقويم Google":

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 access_type=offline&
 include_granted_scopes=true&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 response_type=code&
 client_id=client_id

بعد إكمال عملية OAuth 2.0، من المفترض أن تتم إعادة توجيهك إلى http://localhost/oauth2callback، ما سيؤدي على الأرجح إلى خطأ 404 NOT FOUND ما لم يعرض جهازك المحلي ملفًا على هذا العنوان. تقدّم الخطوة التالية المزيد من التفاصيل حول المعلومات التي يتم عرضها في عنوان URL عندما تتم إعادة توجيه المستخدِم إلى تطبيقك.

الخطوة 5: استبدال رمز التفويض برموز إعادة التحميل والوصول

بعد أن يتلقّى خادم الويب رمز التفويض، يمكنه تبديل رمز التفويض برمز مميّز للوصول.

PHP

لتبديل رمز التفويض برمز مرور، استخدِم الطريقة fetchAccessTokenWithAuthCode:

$access_token = $client->fetchAccessTokenWithAuthCode($_GET['code']);

Python

في صفحة طلب معاودة الاتصال، استخدِم مكتبة google-auth للتحقّق من صحة google-auth ردّ الخادم. بعد ذلك، استخدِم طريقة flow.fetch_token لتبديل رمز التفويض في هذا الردّ برمز مميّز للوصول:

state = flask.session['state']
flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
    'client_secret.json',
    scopes=['https://www.googleapis.com/auth/youtube.force-ssl'],
    state=state)
flow.redirect_uri = flask.url_for('oauth2callback', _external=True)

authorization_response = flask.request.url
flow.fetch_token(authorization_response=authorization_response)

# Store the credentials in the session.
# ACTION ITEM for developers:
#     Store user's access and refresh tokens in your data store if
#     incorporating this code into your real app.
credentials = flow.credentials
flask.session['credentials'] = {
    'token': credentials.token,
    'refresh_token': credentials.refresh_token,
    'token_uri': credentials.token_uri,
    'client_id': credentials.client_id,
    'client_secret': credentials.client_secret,
    'granted_scopes': credentials.granted_scopes}

Ruby

في صفحة معاودة الاتصال، استخدِم مكتبة googleauth للتحقّق من ردّ خادم التفويض. استخدِم طريقة authorizer.handle_auth_callback_deferred لحفظ رمز التفويض وإعادة التوجيه إلى عنوان URL الذي طلب التفويض في الأصل. يؤدي ذلك إلى تأجيل تبادل الرمز من خلال إخفاء النتائج مؤقتًا في جلسة المستخدم.

  target_url = Google::Auth::WebUserAuthorizer.handle_auth_callback_deferred(request)
  redirect target_url

Node.js

لتبديل رمز التفويض برمز مميّز للوصول، استخدِم الطريقة getToken:

const url = require('url');

// Receive the callback from Google's OAuth 2.0 server.
app.get('/oauth2callback', async (req, res) => {
  let q = url.parse(req.url, true).query;

  if (q.error) { // An error response e.g. error=access_denied
    console.log('Error:' + q.error);
  } else if (q.state !== req.session.state) { //check state value
    console.log('State mismatch. Possible CSRF attack');
    res.end('State mismatch. Possible CSRF attack');
  } else { // Get access and refresh tokens (if access_type is offline)

    let { tokens } = await oauth2Client.getToken(q.code);
    oauth2Client.setCredentials(tokens);
});

HTTP/REST

لتبديل رمز التفويض برمز مميّز للوصول، اتصل بنقطة نهاية https://oauth2.googleapis.com/token واضبط المَعلمات التالية:

الحقول
`client_id`	معرِّف العميل الذي تم الحصول عليه من .
`client_secret`	سر العميل الذي تم الحصول عليه من .
`code`	رمز التفويض الذي تم إرجاعه من الطلب الأوّلي
`grant_type`	وفقًا لما هو محدّد في مواصفات OAuth 2.0، يجب ضبط قيمة هذا الحقل على `authorization_code`.
`redirect_uri`	أحد معرّفات الموارد المنتظمة (URI) لإعادة التوجيه المدرَجة لمشروعك في للملف الشخصي المُعطى `client_id`.

يعرض المقتطف التالي نموذج طلب:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=https%3A//oauth2.example.com/code&
grant_type=authorization_code

تستجيب Google لهذا الطلب من خلال عرض عنصر JSON يحتوي على رمز دخول صالح لفترة قصيرة ورمز مميز لإعادة التحميل. يُرجى العلم أنّه لا يتم عرض رمز إعادة التنشيط إلا إذا ضبط تطبيقك المَعلمة access_type على offline في الطلب الأوّلي الذي تم إرساله إلى خادم التفويض في Google.

يحتوي الردّ على الحقول التالية:

الحقول
`access_token`	رمز الموافقة الذي يرسله تطبيقك للموافقة على طلب واجهة برمجة تطبيقات Google.
`expires_in`	المدّة المتبقية لصلاحية رمز الوصول بالثواني
`refresh_token`	رمز مميّز يمكنك استخدامه للحصول على رمز مميّز جديد للوصول تكون رموز إعادة التنشيط صالحة إلى أن يبطل المستخدم إذن الوصول. تجدر الإشارة إلى أنّ هذا الحقل لا يظهر في هذا الردّ إلا إذا ضبطت المَعلمة `access_type` على `offline` في الطلب الأوّلي المُرسَل إلى خادم التفويض في Google.
`scope`	نطاقات الوصول التي يمنحها `access_token` مُعبَّرة عنها كقائمة من سلاسل محددة بمسافة وحساسة لحالة الأحرف.
`token_type`	نوع الرمز المميّز الذي تم إرجاعه. في الوقت الحالي، يتم دائمًا ضبط قيمة هذا الحقل على `Bearer`.

يعرض المقتطف التالي نموذجًا للاستجابة:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/youtube.force-ssl",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

الأخطاء

عند استبدال رمز التفويض برمز وصول، قد تواجه الخطأ التالي بدلاً من الاستجابة المتوقّعة. في ما يلي رموز الأخطاء الشائعة والحلول المقترَحة.

`invalid_grant`

رمز التفويض المقدَّم غير صالح أو التنسيق غير صحيح. يمكنك طلب رمز جديد من خلال إعادة بدء عملية OAuth لطلب الموافقة من المستخدم مجددًا.

الخطوة 6: التحقّق من النطاقات التي منحها المستخدمون

عند طلب نطاقات متعدّدة في آنٍ واحد، قد لا يمنح المستخدمون جميع النطاقات التي يطلبها تطبيقك. يجب أن يتحقّق تطبيقك دائمًا من النطاقات التي منحها المستخدم وأن يتعامل مع أي رفض للنطاقات من خلال إيقاف الميزات ذات الصلة. راجِع مقالة كيفية التعامل مع الأذونات الدقيقة للحصول على مزيد من المعلومات.

PHP

للتحقّق من النطاقات التي منحها المستخدم، استخدِم طريقة getGrantedScope():

// Space-separated string of granted scopes if it exists, otherwise null.
$granted_scopes = $client->getOAuth2Service()->getGrantedScope();

Python

يحتوي عنصر credentials الذي تم إرجاعه على سمة granted_scopes، وهي قائمة بالنطاقات التي منحها المستخدم لتطبيقك.

credentials = flow.credentials
flask.session['credentials'] = {
    'token': credentials.token,
    'refresh_token': credentials.refresh_token,
    'token_uri': credentials.token_uri,
    'client_id': credentials.client_id,
    'client_secret': credentials.client_secret,
    'granted_scopes': credentials.granted_scopes}

Ruby

عند طلب نطاقات متعدّدة في آنٍ واحد، تحقّق من النطاقات التي تم منحها من خلال سمة scope لعنصر credentials.

# User authorized the request. Now, check which scopes were granted.
if credentials.scope.include?(Google::Apis::YoutubeV3::AUTH_YOUTUBE_FORCE_SSL)
  # User authorized permission to see, edit, and permanently delete the
  # YouTube videos, ratings, comments and captions.
  # Calling the APIs, etc
else
  # User didn't authorize the permission.
  # Update UX and application accordingly
end

Node.js

عند طلب نطاقات متعدّدة في آنٍ واحد، تحقّق من النطاقات التي تم منحها من خلال سمة scope لعنصر tokens.

// User authorized the request. Now, check which scopes were granted.
if (tokens.scope.includes('https://www.googleapis.com/auth/youtube.force-ssl'))
{
  // User authorized permission to see, edit, and permanently delete the
  // YouTube videos, ratings, comments and captions.
  // Calling the APIs, etc.
}
else
{
  // User didn't authorize read-only Drive activity permission.
  // Update UX and application accordingly
}

HTTP/REST

للتحقّق مما إذا كان المستخدم قد منح تطبيقك إذن الوصول إلى نطاق معيّن، راجِع الحقل scope في استجابة رمز الوصول. نطاقات الوصول الممنوحة من قِبل رمز الأمان access_token مُعبَّرة عنها كقائمة من السلاسل الحساسة لحالة الأحرف والمفصولة بمسافات.

على سبيل المثال، يشير نموذج ردّ رمز الوصول التالي إلى أنّ المستخدم قد منح تطبيقك إذنًا بالاطّلاع على فيديوهات المستخدم على YouTube وتقييماته وتعليقاته وترجماته وتعديلها وحذفها نهائيًا:

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/youtube.force-ssl",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

طلب بيانات من Google APIs

PHP

استخدِم رمز الوصول لاستدعاء Google APIs من خلال إكمال الخطوات التالية:

إذا كنت بحاجة إلى تطبيق رمز أمان وصول على عنصر Google\Client جديد، مثلاً إذا كنت قد حفظت رمز الأمان في جلسة مستخدم، استخدِم setAccessToken:
```
$client->setAccessToken($access_token);
```
أنشئ عنصر خدمة لواجهة برمجة التطبيقات التي تريد الاتصال بها. يمكنك إنشاء عنصر خدمة من خلال تقديم عنصر Google\Client مفوَّض إلى أداة الإنشاء لواجهة برمجة التطبيقات التي تريد الاتصال بها. على سبيل المثال، للاتصال بواجهة برمجة التطبيقات YouTube Data API:
```
$youtube = new Google_Service_YouTube($client);
```
يمكنك إرسال طلبات إلى خدمة واجهة برمجة التطبيقات باستخدام واجهة برمجة التطبيقات التي يوفّرها عنصر الخدمة. على سبيل المثال، لاسترداد بيانات عن قناة المستخدم المفوَّض على YouTube:
```
$channel = $youtube->channels->listChannels('snippet', array('mine' => $mine));
```

Python

بعد الحصول على رمز دخول، يمكن لتطبيقك استخدام هذا الرمز لمنح الإذن بطلبات واجهة برمجة التطبيقات نيابةً عن حساب مستخدم أو حساب خدمة معيّن. استخدِم بيانات اعتماد التفويض الخاصة بالمستخدم لإنشاء عنصر خدمة لواجهة برمجة التطبيقات التي تريد الاتصال بها، ثم استخدِم هذا العنصر لتقديم طلبات مفوَّضة لواجهة برمجة التطبيقات.

أنشئ عنصر خدمة لواجهة برمجة التطبيقات التي تريد الاتصال بها. يمكنك إنشاء عنصر خدمة من خلال طلب طريقة build في مكتبة googleapiclient.discovery باستخدام اسم واجهة برمجة التطبيقات وإصدارها وبيانات اعتماد المستخدم: على سبيل المثال، لطلب الإصدار 3 من YouTube Data API:
```
from googleapiclient.discovery import build

youtube = build('youtube', 'v3', credentials=credentials)
```
يمكنك إرسال طلبات إلى خدمة واجهة برمجة التطبيقات باستخدام الواجهة التي يوفّرها عنصر الخدمة. على سبيل المثال، لاسترداد بيانات عن قناة المستخدم المفوَّض على YouTube:
```
channel = youtube.channels().list(mine=True, part='snippet').execute()
```

Ruby

بعد الحصول على رمز دخول، يمكن لتطبيقك استخدام هذا الرمز لتقديم طلبات إلى واجهة برمجة التطبيقات بالنيابة عن حساب مستخدم أو حساب خدمة معيّن. استخدِم بيانات اعتماد التفويض الخاصة بالمستخدم لإنشاء عنصر خدمة لواجهة برمجة التطبيقات التي تريد الاتصال بها، ثم استخدِم هذا العنصر لتقديم طلبات مفوَّضة لواجهة برمجة التطبيقات.

أنشئ عنصر خدمة لواجهة برمجة التطبيقات التي تريد الاتصال بها. على سبيل المثال، لطلب البيانات من الإصدار 3 من YouTube Data API:
```
youtube = Google::Apis::YoutubeV3::YouTubeService.new
```
اضبط بيانات الاعتماد في الخدمة:
```
youtube.authorization = credentials
```
يمكنك إرسال طلبات إلى خدمة واجهة برمجة التطبيقات باستخدام الواجهة المقدَّمة من عنصر الخدمة. على سبيل المثال، لاسترداد بيانات عن قناة المستخدم المفوَّض على YouTube:
```
channel = youtube.list_channels(part, :mine => mine)
```

بدلاً من ذلك، يمكن توفير التفويض لكل طريقة على حدة من خلال تقديم المَعلمة options لطريقة معيّنة:

channel = youtube.list_channels(part, :mine => mine, options: { authorization: auth_client })

Node.js

بعد الحصول على رمز وصول وضبطه على عنصر OAuth2، استخدِم العنصر لاستدعاء Google APIs. يمكن لتطبيقك استخدام هذا الرمز المميّز لمنح الإذن بطلبات واجهة برمجة التطبيقات بالنيابة عن حساب مستخدم أو حساب خدمة معيّن. أنشئ عنصر خدمة لواجهة برمجة التطبيقات التي تريد الاتصال بها. على سبيل المثال، يستخدم الرمز البرمجي التالي Google Drive API لعرض أسماء الملفات في Drive الخاص بالمستخدم.

const { google } = require('googleapis');

// Example of using YouTube API to list channels.
var service = google.youtube('v3');
service.channels.list({
  auth: oauth2Client,
  part: 'snippet,contentDetails,statistics',
  forUsername: 'GoogleDevelopers'
}, function (err, response) {
  if (err) {
    console.log('The API returned an error: ' + err);
    return;
  }
  var channels = response.data.items;
  if (channels.length == 0) {
    console.log('No channel found.');
  } else {
    console.log('This channel\'s ID is %s. Its title is \'%s\', and ' +
      'it has %s views.',
      channels[0].id,
      channels[0].snippet.title,
      channels[0].statistics.viewCount);
  }
});

HTTP/REST

بعد أن يحصل تطبيقك على رمز مميّز للوصول، يمكنك استخدام الرمز المميّز لإجراء طلبات إلى واجهة برمجة تطبيقات Google نيابةً عن حساب مستخدم معيّن إذا تم منح نطاق الوصول المطلوب من واجهة برمجة التطبيقات. لإجراء ذلك، أدرِج رمز access_token Bearer access_token ��Authorization يُفضّل استخدام عنوان HTTP كلما أمكن، لأنّ سلاسل طلبات البحث غالبًا ما تكون مرئية في سجلات الخادم. في معظم الحالات، يمكنك استخدام مكتبة عملاء لإعداد طلبات البيانات من واجهات برمجة تطبيقات Google (على سبيل المثال، عند طلب البيانات من YouTube Data API).

تجدر الإشارة إلى أنّ YouTube Data API لا تتيح استخدام حسابات الخدمة إلا لمالكي محتوى YouTube الذين يملكون قنوات متعدّدة على YouTube ويديرونها، مثل شركات الإنتاج وشركات التسجيل.

يمكنك تجربة جميع واجهات برمجة تطبيقات Google والاطّلاع على نطاقات الوصول إليها على مساحة بروتوكول OAuth 2.0.

أمثلة على طلبات HTTP GET

قد تبدو طلبًا موجّهًا إلى نقطة نهاية youtube.channels (YouTube Data API) باستخدام عنوان HTTPAuthorization: Bearer على النحو التالي. يُرجى العِلم أنّك بحاجة إلى تحديد رمز الدخول الخاص بك:

GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

في ما يلي طلب بيانات من واجهة برمجة التطبيقات نفسها للمستخدم الذي تمّت مصادقة بياناته باستخدام مَعلمة سلسلة طلب البحث access_token:

GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

أمثلة على `curl`

يمكنك اختبار هذه الأوامر باستخدام تطبيق سطر الأوامر curl. في ما يلي مثال يستخدم خيار عنوان HTTP (الخيار المفضّل):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true

أو يمكنك بدلاً من ذلك استخدام خيار مَعلمة سلسلة الطلب:

curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

مثال كامل

يطبع المثال التالي عنصرًا بتنسيق JSON يعرض معلومات عن قناة المستخدم على YouTube بعد أن يُثبِّت المستخدم هويته ويفوّض التطبيق لإدارة حسابه على YouTube.

PHP

لتنفيذ هذا المثال:

في ، أضِف عنوان URL للجهاز المحلي إلى قائمة عناوين URL لإعادة التوجيه. على سبيل المثال، أضِف http://localhost:8080.
أنشئ دليلاً جديدًا وانتقِل إليه. على سبيل المثال:
```
mkdir ~/php-oauth2-example
cd ~/php-oauth2-example
```
ثبِّت مكتبة عميل واجهة برمجة التطبيقات للغة PHP باستخدام Composer:
```
composer require google/apiclient:^2.15.0
```
أنشئ الملفَّين index.php وoauth2callback.php باستخدام المحتوى التالي.
شغِّل المثال باستخدام خادم ويب الاختبار المضمّن في PHP:
```
php -S localhost:8080 ~/php-oauth2-example
```

index.php

<?php
require_once __DIR__.'/vendor/autoload.php';

session_start();

$client = new Google\Client();
$client->setAuthConfig('client_secret.json');

// User granted permission as an access token is in the session.
if (isset($_SESSION['access_token']) && $_SESSION['access_token'])
{
  $client->setAccessToken($_SESSION['access_token']);
  
  $youtube = new Google_Service_YouTube($client);
  $channel = $youtube->channels->listChannels('snippet', array('mine' => $mine));
  echo json_encode($channel);
  
}
else
{
  // Redirect users to outh2call.php which redirects users to Google OAuth 2.0
  $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php';
  header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL));
}
?>

oauth2callback.php

<?php
require_once __DIR__.'/vendor/autoload.php';

session_start();

$client = new Google\Client();

// Required, call the setAuthConfig function to load authorization credentials from
// client_secret.json file.
$client->setAuthConfigFile('client_secret.json');
$client->setRedirectUri('http://' . $_SERVER['HTTP_HOST']. $_SERVER['PHP_SELF']);

// Required, to set the scope value, call the addScope function.
$client->addScope(GOOGLE_SERVICE_YOUTUBE::YOUTUBE_FORCE_SSL);

// Enable incremental authorization. Recommended as a best practice.
$client->setIncludeGrantedScopes(true);

// Recommended, offline access will give you both an access and refresh token so that
// your app can refresh the access token without user interaction.
$client->setAccessType("offline");

// Generate a URL for authorization as it doesn't contain code and error
if (!isset($_GET['code']) && !isset($_GET['error']))
{
  // Generate and set state value
  $state = bin2hex(random_bytes(16));
  $client->setState($state);
  $_SESSION['state'] = $state;

  // Generate a url that asks permissions.
  $auth_url = $client->createAuthUrl();
  header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL));
}

// User authorized the request and authorization code is returned to exchange access and
// refresh tokens.
if (isset($_GET['code']))
{
  // Check the state value
  if (!isset($_GET['state']) || $_GET['state'] !== $_SESSION['state']) {
    die('State mismatch. Possible CSRF attack.');
  }

  // Get access and refresh tokens (if access_type is offline)
  $token = $client->fetchAccessTokenWithAuthCode($_GET['code']);

  /** Save access and refresh token to the session variables.
    * ACTION ITEM: In a production app, you likely want to save the
    *              refresh token in a secure persistent storage instead. */
  $_SESSION['access_token'] = $token;
  $_SESSION['refresh_token'] = $client->getRefreshToken();
  
  $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/';
  header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL));
}

// An error response e.g. error=access_denied
if (isset($_GET['error']))
{
  echo "Error: ". $_GET['error'];
}
?>

Python

يستخدم هذا المثال إطار عمل Flask. ويعمل هذا التطبيق على http://localhost:8080، ما يتيح لك اختبار مسار OAuth 2.0. إذا انتقلت إلى عنوان URL هذا، من المفترض أن تظهر لك خمسة روابط:

اختبار طلب بيانات من واجهة برمجة التطبيقات: يشير هذا الرابط إلى صفحة تحاول تنفيذ نموذج طلب بيانات من واجهة برمجة التطبيقات. ويبدأ عملية التفويض إذا لزم الأمر. في حال نجاح العملية، تعرض الصفحة ردّ واجهة برمجة التطبيقات.
اختبار عملية المصادقة مباشرةً: يشير هذا الرابط إلى صفحة تحاول توجيه المستخدم من خلال عملية المصادقة. يطلب التطبيق إذنًا للقيام بما يلي: إرسال طلبات مفوَّضة لواجهات برمجة التطبيقات نيابةً عن المستخدم
إبطال بيانات الاعتماد الحالية: يشير هذا الرابط إلى صفحة تُبطل الأذونات التي منحها المستخدم للتطبيق.
محو بيانات اعتماد جلسة Flask: يؤدي هذا الرابط إلى محو بيانات اعتماد التفويض التي يتم تخزينها في جلسة Flask. يتيح لك ذلك معرفة ما سيحدث إذا حاول مستخدم منح إذن لتطبيقك في جلسة جديدة بعد أن منح إذنًا لتطبيقك في جلسة سابقة. ويتيح لك أيضًا الاطّلاع على ردّ واجهة برمجة التطبيقات الذي سيحصل عليه تطبيقك إذا أبطل مستخدم الأذونات الممنوحة لتطبيقك، وواصل تطبيقك محاولة تفويض طلب باستخدام رمز دخول مُلغى.

ملاحظة: لتشغيل هذا الرمز البرمجي محليًا، يجب أن تكون قد اتّبعت التعليمات الواردة في قسم المتطلّبات الأساسية، بما في ذلك ضبط http://localhost:8080 كعنوان URI صالح لإعادة التوجيه لبيانات الاعتماد وتنزيل ملف client_secret.json لبيانات الاعتماد هذه إلى دليل العمل.

# -*- coding: utf-8 -*-

import os
import flask
import requests

import google.oauth2.credentials
import google_auth_oauthlib.flow
import googleapiclient.discovery

# This variable specifies the name of a file that contains the OAuth 2.0
# information for this application, including its client_id and client_secret.
CLIENT_SECRETS_FILE = "client_secret.json"

# The OAuth 2.0 access scope allows for access to the
# authenticated user's account and requires requests to use an SSL connection.
SCOPES = ['https://www.googleapis.com/auth/youtube.force-ssl']
API_SERVICE_NAME = 'youtube'
API_VERSION = 'v3'

app = flask.Flask(__name__)
# Note: A secret key is included in the sample so that it works.
# If you use this code in your application, replace this with a truly secret
# key. See https://flask.palletsprojects.com/quickstart/#sessions.
app.secret_key = 'REPLACE ME - this value is here as a placeholder.'

@app.route('/')
def index():
  return print_index_table()

@app.route('/test')
def test_api_request():
  if 'credentials' not in flask.session:
  return flask.redirect('authorize')

  # Load credentials from the session.
  credentials = google.oauth2.credentials.Credentials(
    **flask.session['credentials'])

  youtube = googleapiclient.discovery.build(
    API_SERVICE_NAME, API_VERSION, credentials=credentials)

  channel = youtube.channels().list(mine=True, part='snippet').execute()

  # Save credentials back to session in case access token was refreshed.
  # ACTION ITEM: In a production app, you likely want to save these
  #              credentials in a persistent database instead.
  flask.session['credentials'] = credentials_to_dict(credentials)

  return flask.jsonify(**channel)
@app.route('/authorize')
def authorize():
  # Create flow instance to manage the OAuth 2.0 Authorization Grant Flow steps.
  flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
      CLIENT_SECRETS_FILE, scopes=SCOPES)

  # The URI created here must exactly match one of the authorized redirect URIs
  # for the OAuth 2.0 client, which you configured in the API Console. If this
  # value doesn't match an authorized URI, you will get a 'redirect_uri_mismatch'
  # error.
  flow.redirect_uri = flask.url_for('oauth2callback', _external=True)

  authorization_url, state = flow.authorization_url(
      # Enable offline access so that you can refresh an access token without
      # re-prompting the user for permission. Recommended for web server apps.
      access_type='offline',
      # Enable incremental authorization. Recommended as a best practice.
      include_granted_scopes='true')

  # Store the state so the callback can verify the auth server response.
  flask.session['state'] = state

  return flask.redirect(authorization_url)

@app.route('/oauth2callback')
def oauth2callback():
  # Specify the state when creating the flow in the callback so that it can
  # verified in the authorization server response.
  state = flask.session['state']

  flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
      CLIENT_SECRETS_FILE, scopes=SCOPES, state=state)
  flow.redirect_uri = flask.url_for('oauth2callback', _external=True)

  # Use the authorization server's response to fetch the OAuth 2.0 tokens.
  authorization_response = flask.request.url
  flow.fetch_token(authorization_response=authorization_response)

  # Store credentials in the session.
  # ACTION ITEM: In a production app, you likely want to save these
  #              credentials in a persistent database instead.
  credentials = flow.credentials
  
  flask.session['credentials'] = credentials_to_dict(credentials)

  return flask.redirect(flask.url_for('test_api_request'))
  

@app.route('/revoke')
def revoke():
  if 'credentials' not in flask.session:
    return ('You need to <a href="/authorize">authorize</a> before ' +
            'testing the code to revoke credentials.')

  credentials = google.oauth2.credentials.Credentials(
    **flask.session['credentials'])

  revoke = requests.post('https://oauth2.googleapis.com/revoke',
      params={'token': credentials.token},
      headers = {'content-type': 'application/x-www-form-urlencoded'})

  status_code = getattr(revoke, 'status_code')
  if status_code == 200:
    return('Credentials successfully revoked.' + print_index_table())
  else:
    return('An error occurred.' + print_index_table())

@app.route('/clear')
def clear_credentials():
  if 'credentials' in flask.session:
    del flask.session['credentials']
  return ('Credentials have been cleared.<br><br>' +
          print_index_table())

def credentials_to_dict(credentials):
  return {'token': credentials.token,
          'refresh_token': credentials.refresh_token,
          'token_uri': credentials.token_uri,
          'client_id': credentials.client_id,
          'client_secret': credentials.client_secret,
          'granted_scopes': credentials.granted_scopes}

def print_index_table():
  return ('<table>' +
          '<tr><td><a href="/test">Test an API request</a></td>' +
          '<td>Submit an API request and see a formatted JSON response. ' +
          '    Go through the authorization flow if there are no stored ' +
          '    credentials for the user.</td></tr>' +
          '<tr><td><a href="/authorize">Test the auth flow directly</a></td>' +
          '<td>Go directly to the authorization flow. If there are stored ' +
          '    credentials, you still might not be prompted to reauthorize ' +
          '    the application.</td></tr>' +
          '<tr><td><a href="/revoke">Revoke current credentials</a></td>' +
          '<td>Revoke the access token associated with the current user ' +
          '    session. After revoking credentials, if you go to the test ' +
          '    page, you should see an <code>invalid_grant</code> error.' +
          '</td></tr>' +
          '<tr><td><a href="/clear">Clear Flask session credentials</a></td>' +
          '<td>Clear the access token currently stored in the user session. ' +
          '    After clearing the token, if you <a href="/test">test the ' +
          '    API request</a> again, you should go back to the auth flow.' +
          '</td></tr></table>')

if __name__ == '__main__':
  # When running locally, disable OAuthlib's HTTPs verification.
  # ACTION ITEM for developers:
  #     When running in production *do not* leave this option enabled.
  os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1'

  # This disables the requested scopes and granted scopes check.
  # If users only grant partial request, the warning would not be thrown.
  os.environ['OAUTHLIB_RELAX_TOKEN_SCOPE'] = '1'

  # Specify a hostname and port that are set as a valid redirect URI
  # for your API project in the .
  app.run('localhost', 8080, debug=True)

Ruby

يستخدم هذا المثال إطار عمل Sinatra.

require 'googleauth'
require 'googleauth/web_user_authorizer'
require 'googleauth/stores/redis_token_store'

require 'google/apis/youtube_v3'

require 'sinatra'

configure do
  enable :sessions

  # Required, call the from_file method to retrieve the client ID from a
  # client_secret.json file.
  set :client_id, Google::Auth::ClientId.from_file('/path/to/client_secret.json')

  # Required, scope value
  # Access scopes for retrieving data about the user's YouTube channel.
  scope = 'Google::Apis::YoutubeV3::AUTH_YOUTUBE_FORCE_SSL'

  # Required, Authorizers require a storage instance to manage long term persistence of
  # access and refresh tokens.
  set :token_store, Google::Auth::Stores::RedisTokenStore.new(redis: Redis.new)

  # Required, indicate where the API server will redirect the user after the user completes
  # the authorization flow. The redirect URI is required. The value must exactly
  # match one of the authorized redirect URIs for the OAuth 2.0 client, which you
  # configured in the API Console. If this value doesn't match an authorized URI,
  # you will get a 'redirect_uri_mismatch' error.
  set :callback_uri, '/oauth2callback'

  # To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI
  # from the client_secret.json file. To get these credentials for your application, visit
  # https://console.cloud.google.com/apis/credentials.
  set :authorizer, Google::Auth::WebUserAuthorizer.new(settings.client_id, settings.scope,
                          settings.token_store, callback_uri: settings.callback_uri)
end

get '/' do
  # NOTE: Assumes the user is already authenticated to the app
  user_id = request.session['user_id']

  # Fetch stored credentials for the user from the given request session.
  # nil if none present
  credentials = settings.authorizer.get_credentials(user_id, request)

  if credentials.nil?
    # Generate a url that asks the user to authorize requested scope(s).
    # Then, redirect user to the url.
    redirect settings.authorizer.get_authorization_url(request: request)
  end
  
  # User authorized read-only YouTube Data API permission.
  # Example of using YouTube Data API to list user's YouTube channel
  youtube = Google::Apis::YoutubeV3::YouTubeService.new
  channel = youtube.list_channels(part, :mine => mine, options: { authorization: auth_client })
  
  "<pre>#{JSON.pretty_generate(channel.to_h)}</pre>"
end

# Receive the callback from Google's OAuth 2.0 server.
get '/oauth2callback' do
  # Handle the result of the oauth callback. Defers the exchange of the code by
  # temporarily stashing the results in the user's session.
  target_url = Google::Auth::WebUserAuthorizer.handle_auth_callback_deferred(request)
  redirect target_url
end

Node.js

لتنفيذ هذا المثال:

في ، أضِف عنوان URL الخاص بالجهاز المحلي إلى قائمة عناوين URL لإعادة التوجيه. على سبيل المثال، أضِف http://localhost.
تأكَّد من تثبيت إصدار LTS قيد الصيانة أو إصدار LTS نشط أو الإصدار الحالي من Node.js.
أنشئ دليلاً جديدًا وانتقِل إليه. على سبيل المثال:
```
mkdir ~/nodejs-oauth2-example
cd ~/nodejs-oauth2-example
```
ثبِّت مكتبة برمجيّات واجهة برمجة التطبيقات في Google لنظام Node.js باستخدام npm:
```
npm install googleapis
```
أنشئ الملفات main.js باستخدام المحتوى التالي.
شغِّل المثال:
```
node .\main.js
```

main.js

const http = require('http');
const https = require('https');
const url = require('url');
const { google } = require('googleapis');
const crypto = require('crypto');
const express = require('express');
const session = require('express-session');

/**
 * To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI.
 * To get these credentials for your application, visit
 * https://console.cloud.google.com/apis/credentials.
 */
const oauth2Client = new google.auth.OAuth2(
  YOUR_CLIENT_ID,
  YOUR_CLIENT_SECRET,
  YOUR_REDIRECT_URL
);

// Access scopes for YouTube API
const scopes = [
  'https://www.googleapis.com/auth/youtube.force-ssl'
];

/* Global variable that stores user credential in this code example.
 * ACTION ITEM for developers:
 *   Store user's refresh token in your data store if
 *   incorporating this code into your real app.
 *   For more information on handling refresh tokens,
 *   see https://github.com/googleapis/google-api-nodejs-client#handling-refresh-tokens
 */
let userCredential = null;

async function main() {
  const app = express();

  app.use(session({
    secret: 'your_secure_secret_key', // Replace with a strong secret
    resave: false,
    saveUninitialized: false,
  }));

  // Example on redirecting user to Google's OAuth 2.0 server.
  app.get('/', async (req, res) => {
    // Generate a secure random state value.
    const state = crypto.randomBytes(32).toString('hex');
    // Store state in the session
    req.session.state = state;

    // Generate a url that asks permissions for the Drive activity and Google Calendar scope
    const authorizationUrl = oauth2Client.generateAuthUrl({
      // 'online' (default) or 'offline' (gets refresh_token)
      access_type: 'offline',
      /** Pass in the scopes array defined above.
        * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
      scope: scopes,
      // Enable incremental authorization. Recommended as a best practice.
      include_granted_scopes: true,
      // Include the state parameter to reduce the risk of CSRF attacks.
      state: state
    });

    res.redirect(authorizationUrl);
  });

  // Receive the callback from Google's OAuth 2.0 server.
  app.get('/oauth2callback', async (req, res) => {
    // Handle the OAuth 2.0 server response
    let q = url.parse(req.url, true).query;

    if (q.error) { // An error response e.g. error=access_denied
      console.log('Error:' + q.error);
    } else if (q.state !== req.session.state) { //check state value
      console.log('State mismatch. Possible CSRF attack');
      res.end('State mismatch. Possible CSRF attack');
    } else { // Get access and refresh tokens (if access_type is offline)
      let { tokens } = await oauth2Client.getToken(q.code);
      oauth2Client.setCredentials(tokens);

      /** Save credential to the global variable in case access token was refreshed.
        * ACTION ITEM: In a production app, you likely want to save the refresh token
        *              in a secure persistent database instead. */
      userCredential = tokens;
      
      // Example of using YouTube API to list channels.
      var service = google.youtube('v3');
      service.channels.list({
        auth: oauth2Client,
        part: 'snippet,contentDetails,statistics',
        forUsername: 'GoogleDevelopers'
      }, function (err, response) {
        if (err) {
          console.log('The API returned an error: ' + err);
          return;
        }
        var channels = response.data.items;
        if (channels.length == 0) {
          console.log('No channel found.');
        } else {
          console.log('This channel\'s ID is %s. Its title is \'%s\', and ' +
            'it has %s views.',
            channels[0].id,
            channels[0].snippet.title,
            channels[0].statistics.viewCount);
        }
      });
    }
  });

  // Example on revoking a token
  app.get('/revoke', async (req, res) => {
    // Build the string for the POST request
    let postData = "token=" + userCredential.access_token;

    // Options for POST request to Google's OAuth 2.0 server to revoke a token
    let postOptions = {
      host: 'oauth2.googleapis.com',
      port: '443',
      path: '/revoke',
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        'Content-Length': Buffer.byteLength(postData)
      }
    };

    // Set up the request
    const postReq = https.request(postOptions, function (res) {
      res.setEncoding('utf8');
      res.on('data', d => {
        console.log('Response: ' + d);
      });
    });

    postReq.on('error', error => {
      console.log(error)
    });

    // Post the request with data
    postReq.write(postData);
    postReq.end();
  });


  const server = http.createServer(app);
  server.listen(8080);
}
main().catch(console.error);

HTTP/REST

يستخدم مثال Python هذا إطار عمل Flask ومكتبة Requests لعرض مسار الويب في OAuth 2.0. ننصح باستخدام مكتبة برامج Google API للغة Python لتنفيذ هذه العملية. (يستخدم المثال في علامة التبويب Python مكتبة العميل).

import json
import flask
import requests

app = flask.Flask(__name__)

# To get these credentials (CLIENT_ID CLIENT_SECRET) and for your application, visit
# https://console.cloud.google.com/apis/credentials.
CLIENT_ID = '123456789.apps.googleusercontent.com'
CLIENT_SECRET = 'abc123'  # Read from a file or environmental variable in a real app

# Access scopes for YouTube API
SCOPE = 'https://www.googleapis.com/auth/youtube.force-ssl'

# Indicate where the API server will redirect the user after the user completes
# the authorization flow. The redirect URI is required. The value must exactly
# match one of the authorized redirect URIs for the OAuth 2.0 client, which you
# configured in the API Console. If this value doesn't match an authorized URI,
# you will get a 'redirect_uri_mismatch' error.
REDIRECT_URI = 'http://example.com/oauth2callback'

@app.route('/')
def index():
  if 'credentials' not in flask.session:
    return flask.redirect(flask.url_for('oauth2callback'))

  credentials = json.loads(flask.session['credentials'])

  if credentials['expires_in'] <= 0:
    return flask.redirect(flask.url_for('oauth2callback'))
  else: 
    headers = {'Authorization': 'Bearer {}'.format(credentials['access_token'])}
    req_uri = 'https://www.googleapis.com/youtube/v3/channels/list'
    r = requests.get(req_uri, headers=headers)
    return r.text 

@app.route('/oauth2callback')
def oauth2callback():
  if 'code' not in flask.request.args:
    state = str(uuid.uuid4())
    flask.session['state'] = state
    # Generate a url that asks permissions for the Drive activity
    # and Google Calendar scope. Then, redirect user to the url.
    auth_uri = ('https://accounts.google.com/o/oauth2/v2/auth?response_type=code'
                '&client_id={}&redirect_uri={}&scope={}&state={}').format(CLIENT_ID, REDIRECT_URI,
                                                                          SCOPE, state)
    return flask.redirect(auth_uri)
  else:
    if 'state' not in flask.request.args or flask.request.args['state'] != flask.session['state']:
      return 'State mismatch. Possible CSRF attack.', 400

    auth_code = flask.request.args.get('code')
    data = {'code': auth_code,
            'client_id': CLIENT_ID,
            'client_secret': CLIENT_SECRET,
            'redirect_uri': REDIRECT_URI,
            'grant_type': 'authorization_code'}

    # Exchange authorization code for access and refresh tokens (if access_type is offline)
    r = requests.post('https://oauth2.googleapis.com/token', data=data)
    flask.session['credentials'] = r.text
    return flask.redirect(flask.url_for('index'))

if __name__ == '__main__':
  import uuid
  app.secret_key = str(uuid.uuid4())
  app.debug = False
  app.run()

قواعد التحقّق من صحة معرّف الموارد المنتظم (URI) الخاص بإعادة التوجيه

تطبّق Google قواعد التحقّق التالية على عناوين URL لإعادة التوجيه من أجل مساعدة المطوّرين في الحفاظ على أمان تطبيقاتهم. يجب أن تلتزم عناوين URL لإعادة التوجيه بهذه القواعد. اطّلِع على الفقرة 3 من RFC 3986 للاطّلاع على التعريفات التالية: النطاق والمضيف والمسار وطلب البحث والمخطط ومعلومات المستخدم، والمذكورة أدناه.

قواعد التحقّق
المخطّط	يجب أن تستخدم معرّفات الموارد المنتظمة لإعادة التوجيه مخطّط HTTPS، وليس HTTP العادي. معرّفات الموارد المنتظمة للمضيف المحلي (بما في ذلك عناوين IP للمضيف المحلي) معفاة من هذه القاعدة.
المضيف	لا يمكن أن تكون المضيفات عناوين IP أساسية. ويتم استثناء عناوين IP للمضيف المحلي من هذه القاعدة.
النطاق	يجب أن تنتمي نطاقات المستوى الأعلى للمضيف (نطاقات المستوى الأعلى) إلى قائمة اللاحقات العلنية. لا يمكن أن تكون النطاقات المضيفة `“googleusercontent.com”`. لا يمكن أن تحتوي معرّفات الموارد المنتظمة (URI) لإعادة التوجيه على نطاقات مختصرة لعناوين URL (مثل `goo.gl`) ما لم يكن يملك التطبيق النطاق. بالإضافة إلى ذلك، إذا اختار تطبيق يملك نطاقًا لمختصر عناوين URL أن يعيد توجيه المستخدمين إلى ذلك النطاق، يجب أن يحتوي عنوان URL لإعادة التوجيه على `“/google-callback/”` في مساره أو ينتهي ب`“/google-callback”`.
Userinfo	لا يمكن أن تحتوي عناوين URL لإعادة التوجيه على المكوّن الفرعي userinfo.
المسار	لا يمكن أن تحتوي عناوين URL لإعادة التوجيه على مسار عبور (يُعرف أيضًا باسم الرجوع إلى الدليل)، والذي يُمثّله ترميز `“/..”` أو `“\..”` أو عنوان URL.
طلب بحث	لا يمكن أن تحتوي معرّفات الموارد المنتظمة (URI) لإعادة التوجيه على عمليات إعادة توجيه مفتوحة.
المقاطع	لا يمكن أن تحتوي عناوين URL لإعادة التوجيه على مكوّن العنصر.
الشخصيات	لا يمكن أن تحتوي عناوين URL لإعادة التوجيه على أحرف معيّنة، بما في ذلك: أحرف البدل (`'*'`) أحرف ASCII غير القابلة للطباعة ترميزات النسبة المئوية غير الصالحة (أي ترميز نسبة مئوية لا يتّبع تنسيق ترميز عنوان URL الذي يتكون من علامة النسبة المئوية متبوعة برقمين سداسيَين عشريَين) الأحرف الفارغة (حرف NULL مشفّر، مثل `%00`، `%C0%80`)

التفويض المتزايد

في بروتوكول OAuth 2.0، يطلب تطبيقك تفويضًا للوصول إلى الموارد التي يتم تحديدها باستخدام النطاقات. من أفضل الممارسات التي تُحسِّن تجربة المستخدمين هي طلب الإذن بالوصول إلى الموارد في الوقت الذي تحتاج فيه إليها. لتفعيل هذه الممارسة، يتيح خادم التفويض في Google التفويض المتزايد. تتيح لك هذه الميزة طلب النطاقات حسب الحاجة، وإذا منح المستخدم الإذن بالنطاق الجديد، يتم عرض رمز تفويض يمكن مبادلته برمز مميز يحتوي على جميع النطاقات التي منحها المستخدم للمشروع.

على سبيل المثال، لنفترض أنّ هناك تطبيقًا يساعد المستخدمين في تحديد الأحداث المحلية المثيرة للاهتمام. يتيح التطبيق للمستخدمين مشاهدة فيديوهات عن الفعاليات وتقييم الفيديوهات وإضافة الفيديوهات إلى قوائم التشغيل. يمكن للمستخدمين أيضًا استخدام التطبيق لإضافة أحداث إلى تقويمات Google.

في هذه الحالة، قد لا يحتاج التطبيق أو يطلب الوصول إلى أي نطاقات في وقت تسجيل الدخول. ومع ذلك، إذا حاول المستخدم تقييم فيديو أو إضافة فيديو إلى ملف شخصي في قائمة تشغيل أو تنفيذ إجراء آخر على YouTube، يمكن للتطبيق طلب الوصول إلى ملف شخصي في نطاق https://www.googleapis.com/auth/youtube.force-ssl. وبالمثل، يمكن للتطبيق طلب الوصول إلى النطاق https://www.googleapis.com/auth/calendar إذا حاول المستخدم إضافة حدث تقويم.

لتنفيذ التفويض المتزايد، عليك إكمال العملية العادية لطلب رمز ميزات الوصول، ولكن تأكَّد من أنّ طلب التفويض يتضمّن النطاقات التي تم منحها سابقًا. تسمح هذه الطريقة لتطبيقك بتجنُّب إدارة العديد من الرموز المميّزة للوصول.

تنطبق القواعد التالية على رمز دخول تم الحصول عليه من عملية تفويض متزايدة:

يمكن استخدام الرمز المميّز للوصول إلى الموارد التي تتوافق مع أيّ من النطاقات المضمّنة في الإذن الجديد المجمّع.
عند استخدام الرمز المميّز لإعادة التحميل للتفويض المجمّع من أجل الحصول على رمز مميّز للوصول، يمثّل رمز الوصول التفويض المجمّع ويمكن استخدامه لأي من قيم scope المضمّنة في الاستجابة.
يتضمّن التفويض المجمّع جميع النطاقات التي منحها المستخدم لمشروع واجهة برمجة التطبيقات حتى إذا تم طلب المنح من عملاء مختلفين. على سبيل المثال، إذا منح مستخدم إذن الوصول إلى نطاق واحد باستخدام برنامج كمبيوتر مكتبي للتطبيق، ثم منح إذن وصول آخر إلى تطبيق مماثل من خلال برنامج متوافق مع الأجهزة الجوّالة، سيتضمّن التفويض المجمّع كلا النطاقَين.
في حال إبطال رمز تمثيل يمثّل تفويضًا مجمعًا، يتم إبطال الوصول إلى جميع نطاقات التفويض نيابةً عن المستخدم المرتبط في الوقت نفسه.

تستخدم نماذج الرموز البرمجية الخاصة باللغة في الخطوة 1: ضبط معلَمات التفويض ونموذج عنوان URL لإعادة التوجيه في HTTP/REST في الخطوة 2: إعادة التوجيه إلى خادم OAuth 2.0 من Google جميعها التفويض المتزايد. تعرض أيضًا نماذج الرموز أدناه الرمز الذي تحتاج إلى إضافته لاستخدام التفويض المتزايد.

PHP

$client->setIncludeGrantedScopes(true);

Python

في Python، اضبط وسيطة الكلمة الرئيسية include_granted_scopes على true لمحاولة التأكّد من أنّ طلب التفويض يتضمّن النطاقات التي تم منحها سابقًا. من المحتمل جدًا أنّ include_granted_scopes لن تكون الوسيطة الوحيدة للكلمة الرئيسية التي تحدّدها، كما هو موضح في المثال أدناه.

authorization_url, state = flow.authorization_url(
    # Enable offline access so that you can refresh an access token without
    # re-prompting the user for permission. Recommended for web server apps.
    access_type='offline',
    # Enable incremental authorization. Recommended as a best practice.
    include_granted_scopes='true')

Ruby

auth_client.update!(
  :additional_parameters => {"include_granted_scopes" => "true"}
)

Node.js

const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined above.
    * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as a best practice.
  include_granted_scopes: true
});

HTTP/REST

في هذا المثال، يطلب التطبيق المُرسِل إذن الوصول لاسترداد data العميل في "إحصاءات YouTube" بالإضافة إلى أي إذن وصول آخر قد منحه العميل للتطبيق.

GET https://accounts.google.com/o/oauth2/v2/auth?
  scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.readonly&
  access_type=offline&
  state=security_token%3D138rk%3Btarget_url%3Dhttp...index&
  redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
  response_type=code&
  client_id=client_id&
  include_granted_scopes=true

Refreshing an access token (offline access)

Access tokens periodically expire and become invalid credentials for a related API request. You can refresh an access token without prompting the user for permission (including when the user is not present) if you requested offline access to the scopes associated with the token.

If you use a Google API Client Library, the client object refreshes the access token as needed as long as you configure that object for offline access.
If you are not using a client library, you need to set the access_type HTTP query parameter to offline when redirecting the user to Google's OAuth 2.0 server. In that case, Google's authorization server returns a refresh token when you exchange an authorization code for an access token. Then, if the access token expires (or at any other time), you can use a refresh token to obtain a new access token.

Requesting offline access is a requirement for any application that needs to access a Google API when the user is not present. For example, an app that performs backup services or executes actions at predetermined times needs to be able to refresh its access token when the user is not present. The default style of access is called online.

Server-side web applications, installed applications, and devices all obtain refresh tokens during the authorization process. Refresh tokens are not typically used in client-side (JavaScript) web applications.

PHP

If your application needs offline access to a Google API, set the API client's access type to offline:

$client->setAccessType("offline");

بعد أن يمنح المستخدم إذن الوصول بلا إنترنت إلى النطاقات المطلوبة، يمكنك مواصلة استخدام العميل لواجهة برمجة التطبيقات للوصول إلى Google APIs بالنيابة عن المستخدم عندما يكون بلا إنترنت. سيُعيد عنصر العميل تحميل رمز الوصول المميّز حسب الحاجة.

Python

في Python، اضبط مَعلمة الكلمة الرئيسية access_type على offline لضمان أنّه سيكون بإمكانك إعادة تحميل رمز الوصول بدون الحاجة إلى إعادة طلب الإذن من المستخدم. من المحتمل جدًا ألا تكون access_type هي الوسيطة الوحيدة للكلمة الرئيسية التي تحدّدها، كما هو موضّح في المثال أدناه.

authorization_url, state = flow.authorization_url(
    # Enable offline access so that you can refresh an access token without
    # re-prompting the user for permission. Recommended for web server apps.
    access_type='offline',
    # Enable incremental authorization. Recommended as a best practice.
    include_granted_scopes='true')

Ruby

إذا كان تطبيقك يحتاج إلى الوصول إلى واجهة برمجة تطبيقات Google بلا إنترنت، اضبط نوع وصول عميل واجهة برمجة التطبيقات على offline:

auth_client.update!(
  :additional_parameters => {"access_type" => "offline"}
)

Node.js

const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined above.
    * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as a best practice.
  include_granted_scopes: true
});

تنتهي صلاحية رموز الوصول. ستستخدم هذه المكتبة تلقائيًا رمز إعادة التنشيط للحصول على رمز وصول جديد إذا كان على وشك انتهاء صلاحيته. إنّ الطريقة السهلة للتأكّد من تخزين أحدث الرموز المميّزة دائمًا هي استخدام حدث "الرموز المميّزة":

oauth2Client.on('tokens', (tokens) => {
  if (tokens.refresh_token) {
    // store the refresh_token in your secure persistent database
    console.log(tokens.refresh_token);
  }
  console.log(tokens.access_token);
});

لا يحدث حدث الرموز المميّزة هذا إلا في التفويض الأول، ويجب ضبط access_type على offline عند استدعاء طريقة generateAuthUrl لتلقّي رمز إعادة التنشيط. إذا سبق لك منح تطبيقك الأذونات المطلوبة بدون ضبط القيود المناسبة لتلقّي رمز تنشيط جديد، عليك إعادة تفويض التطبيق لتلقّي رمز تنشيط جديد.

لضبط refresh_token في وقت لاحق، يمكنك استخدام طريقة setCredentials:

oauth2Client.setCredentials({
  refresh_token: `STORED_REFRESH_TOKEN`
});

بعد أن يحصل العميل على رمز مميز لإعادة التحميل، سيتم الحصول على رموز الوصول وإعادة تحميلها تلقائيًا في الطلب التالي إلى واجهة برمجة التطبيقات.

HTTP/REST

لإعادة تحميل رمز مميّز للوصول، يُرسِل تطبيقك طلبًا عبر HTTPS POST إلى خادم التفويض في Google‏ (https://oauth2.googleapis.com/token) الذي يتضمّن المَعلمات التالية:

الحقول
`client_id`	معرِّف العميل الذي تم الحصول عليه من .
`client_secret`	سر العميل الذي تم الحصول عليه من
`grant_type`	كما هو محدّد في مواصفات OAuth 2.0، يجب ضبط قيمة هذا الحقل على `refresh_token`.
`refresh_token`	الرمز المميّز لإعادة التحميل الذي تم إرجاعه من عملية استبدال رمز التفويض

يعرض المقتطف التالي نموذج طلب:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

ما دام المستخدم لم يُبطل الإذن الذي منحه للتطبيق، يعرض خادم الرموز المميّزة عنصر JSON يحتوي على رمز مميّز جديد للوصول. يعرض المقتطف التالي نموذجًا للاستجابة:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "token_type": "Bearer"
}

يُرجى العلم أنّ هناك حدودًا لعدد رموز إعادة التنشيط التي سيتم إصدارها، وحدّ واحد لكل مجموعة عميل/مستخدم، وحدّ آخر لكل مستخدم في جميع العملاء. يجب حفظ الرموز المميّزة لإعادة التحميل في مساحة تخزين طويلة الأمد ومواصلة استخدامها ما دامت صالحة. إذا طلب تطبيقك عددًا كبيرًا جدًا من رموز إعادة التنشيط، قد يواجه هذه الحدود، وفي هذه الحالة، سيتوقّف رموز إعادة التنشيط القديمة عن العمل.

إبطال رمز مميّز

في بعض الحالات، قد يريد المستخدم إبطال إذن الوصول الممنوح لتطبيق معيّن. يمكن للمستخدم إبطال إذن الوصول من خلال الانتقال إلى إعدادات الحساب. يمكنك الاطّلاع على قسم إزالة إذن الوصول إلى الموقع الإلكتروني أو التطبيق ضمن المقالة "المواقع الإلكترونية والتطبيقات التابعة لجهات خارجية التي يمكنها الوصول إلى حسابك" في مستند الدعم للحصول على مزيد من المعلومات.

من الممكن أيضًا أن يُلغي التطبيق بشكل آلي الإذن الذي منحه له. من المهم أن يتم إلغاء التفويض آليًا في الحالات التي يُلغي فيها المستخدم الاشتراك أو يزيل تطبيقًا أو تغيّرت فيها موارد واجهة برمجة التطبيقات المطلوبة من أحد التطبيقات بشكل كبير. بعبارة أخرى، يمكن أن يتضمّن جزء من عملية الإزالة طلبًا لواجهة برمجة التطبيقات لضمان إزالة الأذونات التي تم منح التطبيق إياها في السابق.

PHP

لإبطال رمز مميّز آليًا، يمكنك الاتصال بـ revokeToken():

$client->revokeToken();

Python

لإبطال رمز مميّز آليًا، قدِّم طلبًا إلى عنوان https://oauth2.googleapis.com/revoke يتضمّن الرمز المميّز كمَعلمة ويضبط العنوان Content-Type:

requests.post('https://oauth2.googleapis.com/revoke',
    params={'token': credentials.token},
    headers = {'content-type': 'application/x-www-form-urlencoded'})

Ruby

لإبطال رمز مميّز آليًا، أرسِل طلب HTTP إلى نقطة نهاية oauth2.revoke:

uri = URI('https://oauth2.googleapis.com/revoke')
response = Net::HTTP.post_form(uri, 'token' => auth_client.access_token)

يمكن أن يكون الرمز المميّز رمز دخول أو رمزًا مميزًا لإعادة التحميل. إذا كان الرمز المميّز هو رمز دخول وكان لديه رمز مميّز مقابل لإعادة التحميل، سيتم أيضًا إلغاء رمز إعادة التحميل.

إذا تمت معالجة الإبطال بنجاح، يكون رمز حالة الاستجابة هو 200. في حالات الخطأ، يتم عرض رمز الحالة 400 مع رمز خطأ.

Node.js

لإبطال رمز مميّز آليًا، أرسِل طلب POST عبر HTTPS إلى نقطة نهاية /revoke:

const https = require('https');

// Build the string for the POST request
let postData = "token=" + userCredential.access_token;

// Options for POST request to Google's OAuth 2.0 server to revoke a token
let postOptions = {
  host: 'oauth2.googleapis.com',
  port: '443',
  path: '/revoke',
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Content-Length': Buffer.byteLength(postData)
  }
};

// Set up the request
const postReq = https.request(postOptions, function (res) {
  res.setEncoding('utf8');
  res.on('data', d => {
    console.log('Response: ' + d);
  });
});

postReq.on('error', error => {
  console.log(error)
});

// Post the request with data
postReq.write(postData);
postReq.end();

يمكن أن تكون مَعلمة الرمز المميّز رمز دخول أو رمزًا مميّزًا لإعادة التحميل. إذا كان الرمز المميّز هو رمز دخول وكان لديه رمز مميّز مقابل لإعادة التحميل، سيتم أيضًا إلغاء رمز إعادة التحميل.

إذا تمت معالجة الإبطال بنجاح، يكون رمز حالة الاستجابة هو 200. في حالات الخطأ، يتم عرض رمز الحالة 400 مع رمز خطأ.

HTTP/REST

لإبطال رمز مميّز آليًا، يُرسِل تطبيقك طلبًا إلى https://oauth2.googleapis.com/revoke ويُدرِج الرمز المميّز كمَعلمة:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

إذا تمت معالجة الإبطال بنجاح، يكون رمز حالة HTTP للاستجابة هو 200. في حالات الخطأ، يتم عرض رمز حالة HTTP 400 مع رمز خطأ.

تنفيذ ميزة "الحماية العابرة للحساب"

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

في ما يلي بعض الأمثلة على أنواع الأحداث التي ترسلها خدمة "الحماية بين الحسابات" من Google إلى تطبيقك:

https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
https://schemas.openid.net/secevent/oauth/event-type/token-revoked
https://schemas.openid.net/secevent/risc/event-type/account-disabled

اطّلِع على صفحة "حماية حسابات المستخدمين من خلال ميزة "الحماية العابرة للحساب" للحصول على مزيد من المعلومات عن كيفية تنفيذ ميزة "الحماية العابرة للحساب" والاطّلاع على القائمة الكاملة للأحداث المتاحة.

استخدام OAuth 2.0 لتطبيقات خادم الويب

مكتبات العملاء

المتطلبات الأساسية

تفعيل واجهات برمجة التطبيقات لمشروعك

إنشاء بيانات اعتماد التفويض

تحديد نطاقات الوصول

المتطلبات الخاصة باللغة

PHP

Python

Ruby

Node.js

HTTP/REST

الحصول على رموز دخول OAuth 2.0

الخطوة 1: ضبط مَعلمات التفويض

PHP

Python

Ruby

Node.js

HTTP/REST

الخطوة 2: إعادة التوجيه إلى خادم OAuth 2.0 من Google

PHP

Python

Ruby

Node.js

HTTP/REST

نموذج إعادة توجيه إلى خادم التفويض في Google

الخطوة 3: تطلب Google من المستخدم الموافقة

الأخطاء

admin_policy_enforced

disallowed_useragent

Android

iOS

org_internal

invalid_client

invalid_grant

redirect_uri_mismatch

invalid_request

الخطوة 4: معالجة استجابة خادم OAuth 2.0

نموذج استجابة خادم OAuth 2.0

الخطوة 5: استبدال رمز التفويض برموز إعادة التحميل والوصول

PHP

Python

Ruby

Node.js

HTTP/REST

الأخطاء

invalid_grant

الخطوة 6: التحقّق من النطاقات التي منحها المستخدمون

PHP

Python

Ruby

Node.js

HTTP/REST

طلب بيانات من Google APIs

PHP

Python

Ruby

Node.js

HTTP/REST

أمثلة على طلبات HTTP GET

أمثلة على curl

مثال كامل

PHP

index.php

oauth2callback.php

Python

Ruby

Node.js

main.js

HTTP/REST

قواعد التحقّق من صحة معرّف الموارد المنتظم (URI) الخاص بإعادة التوجيه

التفويض المتزايد

PHP

Python

Ruby

Node.js

HTTP/REST

Refreshing an access token (offline access)

PHP

Python

`admin_policy_enforced`

`disallowed_useragent`

`org_internal`

`invalid_client`

`invalid_grant`

`redirect_uri_mismatch`

`invalid_request`

`invalid_grant`

أمثلة على `curl`