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

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

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

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

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

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

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

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

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

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

• Go
• Java
• .NET
• Node.js
• PHP
• Python
• Ruby

ملاحظة مهمة: إنّ مكتبة برمجة تطبيقات Google العميل لبرنامج JavaScript وتسجيل الدخول باستخدام حساب Google مخصّصَتان فقط للتعامل مع بروتوكول OAuth 2.0 في متصفّح المستخدم. إذا كنت تريد استخدام JavaScript على جانب الخادم لإدارة التفاعلات مع Google باستخدام بروتوكول OAuth 2.0، ننصحك باستخدام مكتبة Node.js على منصة الخلفية.

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

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

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

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

1. Open the API Library في Google API Console.
2. If prompted, select a project, or create a new one.
3. API Library تُدرج جميع واجهات برمجة التطبيقات المتاحة، مجمّعة حسب عائلة المنتجات ومدى رواجها. إذا لم يكن واجهة برمجة التطبيقات التي تريد تفعيلها ظاهرة في القائمة، استخدِم ميزة البحث للعثور عليها، أو انقر على عرض الكل في مجموعة المنتجات التي تنتمي إليها.
4. اختَر واجهة برمجة التطبيقات التي تريد تفعيلها، ثم انقر على الزر تفعيل.
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

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

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

1. Go to the Credentials page.
2. انقر على إنشاء بيانات اعتماد > معرِّف عميل OAuth.
3. اختَر نوع التطبيق تطبيق الويب.
4. املأ النموذج وانقر على إنشاء. يجب أن تحدِّد التطبيقات التي تستخدم لغات وأطر عمل مثل PHP وJava وPython وRuby و .NET معرّفات الموارد المنتظمة (URI) لإعادة التوجيه المعتمَدة. معرّفات الموارد المنتظمة لإعادة التوجيه هي نقاط النهاية التي يمكن لخادم OAuth 2.0 إرسال الردود إليها. يجب أن تلتزم نقاط النهاية هذه بقواعد التحقّق من Google.

   للاختبار، يمكنك تحديد عناوين URL تشير إلى الجهاز المحلي، مثل http://localhost:8080. مع وضع ذلك في الاعتبار، يُرجى العلم أنّ جميع الأمثلة الواردة في هذا المستند تستخدِم http://localhost:8080 كمعرّف الموارد المنتظم لإعادة التوجيه.

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

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

ملاحظة مهمة: لا تخزِّن ملف client_secret.json في مكان يمكن للجميع الوصول إليه. بالإضافة إلى ذلك، إذا شاركت رمز المصدر لتطبيقك على GitHub مثلاً، يمكنك تخزين ملف client_secret.json خارج شجرة المصدر لتجنُّب مشاركة بيانات اعتماد العميل بدون قصد.

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

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

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

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

يحتوي مستند نطاقات واجهة برمجة التطبيقات 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

• مكتبات برامج واجهتَي برمجة التطبيقات Drive وCalendar من Google:

  gem install google-apis-drive_v3 google-apis-calendar_v3

• إطار عمل تطبيق الويب 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 الذي يتطلّب تفويض المستخدم.

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

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

الخطوة 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 الاختياريتين.

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

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\Drive::DRIVE_METADATA_READONLY, Google\Service\Calendar::CALENDAR_READONLY]);

// 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('[e-mail]');

// 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 الاختياريتين.

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

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/drive.metadata.readonly',
            'https://www.googleapis.com/auth/calendar.readonly'])

# 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='[e-mail]',
    # Optional, set prompt to 'consent' will prompt the user for consent
    prompt='consent')

Ruby

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

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

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

require 'google/apis/drive_v3'
require 'google/apis/calendar_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 
# Access scopes for two non-Sign-In scopes: Read-only Drive activity and Google Calendar.
scope = ['Google::Apis::DriveV3::AUTH_DRIVE_METADATA_READONLY',
         'Google::Apis::CalendarV3::AUTH_CALENDAR_READONLY']

# 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 two non-Sign-In scopes: Read-only Drive activity and Google Calendar.
const scopes = [
  'https://www.googleapis.com/auth/drive.metadata.readonly',
  'https://www.googleapis.com/auth/calendar.readonly'
];

// 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	مطلوب معرّف العميل لتطبيقك. يمكنك العثور على هذه القيمة في API Console Credentials page.
redirect_uri	مطلوب لتحديد المكان الذي يعيد فيه خادم واجهة برمجة التطبيقات توجيه المستخدم بعد إكماله عملية التفويض. يجب أن تتطابق القيمة تمامًا مع أحد عناوين URL المعتمَدة لإعادة التوجيه لملف تعريف العميل في OAuth 2.0، والذي أعددته في API Console Credentials pageالعميل. إذا لم تتطابق هذه القيمة مع عنوان URL مُعتمَد لإعادة التوجيه للclient_id المقدَّمة، ستظهر لك رسالة خطأ redirect_uri_mismatch. يُرجى العلم أنّه يجب أن يتطابق كلّ من مخطّط http أو https وحالة الأحرف والشرطة المائلة المتّبعة (/).
response_type	مطلوب لتحديد ما إذا كانت نقطة نهاية Google OAuth 2.0 تعرض رمز تفويض. اضبط قيمة المَعلمة على code لتطبيقات خادم الويب.
scope	مطلوب قائمة مفصولة بالفواصل بالنطاقات التي تحدِّد الموارد التي يمكن لتطبيقك الوصول إليها نيابةً عن المستخدم وتُستخدَم هذه القيم لعرض شاشة الموافقة التي تعرِضها Google للمستخدم. تتيح النطاقات لتطبيقك طلب الوصول إلى الموارد التي يحتاج إليها فقط، مع السماح للمستخدمين أيضًا بالتحكم في مقدار الوصول الذي يمنحه لتطبيقك. وبالتالي، هناك علاقة عكسية بين عدد النطاقات المطلوبة واحتمالية الحصول على موافقة المستخدم. ننصحك بأن يطلب تطبيقك الوصول إلى نطاقات التفويض في السياق كلما أمكن ذلك. من خلال طلب الوصول إلى بيانات المستخدمين في السياق، من خلال المصادقة المتزايدة، يمكنك مساعدة المستخدمين على فهم سبب احتياج تطبيقك إلى إذن الوصول الذي يطلبه بسهولة أكبر.
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

1. أنشئ عنوان URL لطلب الوصول من خادم OAuth 2.0 في Google:

   $auth_url = $client->createAuthUrl();

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

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

Python

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

return flask.redirect(authorization_url)

Ruby

1. أنشئ عنوان URL لطلب الوصول من خادم OAuth 2.0 في Google:

   auth_uri = authorizer.get_authorization_url(request: request)

2. أعِد توجيه المستخدم إلى auth_uri.

Node.js

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

   res.redirect(authorizationUrl);

HTTP/REST

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

يظهر أدناه مثال على عنوان URL، مع فواصل أسطر ومسافات لتسهيل القراءة.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.readonly&
 access_type=offline&
 include_granted_scopes=true&
 response_type=code&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/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) المعتمَدة لإعادة التوجيه في Google API Console Credentials page.

قد تشير المَعلمة 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//www.googleapis.com/auth/drive.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.readonly&
 access_type=offline&
 include_granted_scopes=true&
 response_type=code&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/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/drive.metadata.readonly'],
    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	معرِّف العميل الذي تم الحصول عليه من API Console Credentials page.
client_secret	سر العميل الذي تم الحصول عليه من API Console Credentials page.
code	رمز التفويض الذي تم إرجاعه من الطلب الأوّلي
grant_type	وفقًا لما هو محدّد في مواصفات OAuth 2.0، يجب ضبط قيمة هذا الحقل على authorization_code.
redirect_uri	أحد معرّفات الموارد المنتظمة (URI) لإعادة التوجيه المدرَجة لمشروعك في API Console Credentials page للملف الشخصي المُعطى 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.

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

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

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
  "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();

// Determine which scopes user granted and build a dictionary
$granted_scopes_dict = [
  'Drive' => str_contains($granted_scopes, Google\Service\Drive::DRIVE_METADATA_READONLY),
  'Calendar' => str_contains($granted_scopes, Google\Service\Calendar::CALENDAR_READONLY)
];

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}

تتحقّق الوظيفة التالية من النطاقات التي منحها المستخدم لتطبيقك.

def check_granted_scopes(credentials):
  features = {}
  if 'https://www.googleapis.com/auth/drive.metadata.readonly' in credentials['granted_scopes']:
    features['drive'] = True
  else:
    features['drive'] = False

  if 'https://www.googleapis.com/auth/calendar.readonly' in credentials['granted_scopes']:
    features['calendar'] = True
  else:
    features['calendar'] = False

  return features

Ruby

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

# User authorized the request. Now, check which scopes were granted.
if credentials.scope.include?(Google::Apis::DriveV3::AUTH_DRIVE_METADATA_READONLY)
  # User authorized read-only Drive activity permission.
  # Calling the APIs, etc
else
  # User didn't authorize read-only Drive activity permission.
  # Update UX and application accordingly
end

# Check if user authorized Calendar read permission.
if credentials.scope.include?(Google::Apis::CalendarV3::AUTH_CALENDAR_READONLY)
  # User authorized Calendar read permission.
  # Calling the APIs, etc.
else
  # User didn't authorize Calendar read 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/drive.metadata.readonly'))
{
  // User authorized read-only Drive activity permission.
  // Calling the APIs, etc.
}
else
{
  // User didn't authorize read-only Drive activity permission.
  // Update UX and application accordingly
}

// Check if user authorized Calendar read permission.
if (tokens.scope.includes('https://www.googleapis.com/auth/calendar.readonly'))
{
  // User authorized Calendar read permission.
  // Calling the APIs, etc.
}
else
{
  // User didn't authorize Calendar read permission.
  // Update UX and application accordingly
}

HTTP/REST

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

على سبيل المثال، يشير نموذج ردّ رمز الوصول التالي إلى أنّ المستخدم قد منح تطبيقك إذن الوصول إلى أذونات نشاط Drive وأحداث "تقويم Google" للقراءة فقط:

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

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

PHP

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

1. إذا كنت بحاجة إلى تطبيق رمز أمان وصول على عنصر Google\Client جديد، مثلاً إذا كنت قد حفظت رمز الأمان في جلسة مستخدم، استخدِم setAccessToken:

   $client->setAccessToken($access_token);

2. أنشئ عنصر خدمة لواجهة برمجة التطبيقات التي تريد الاتصال بها. يمكنك إنشاء عنصر خدمة من خلال تقديم عنصر Google\Client مفوَّض إلى أداة الإنشاء لواجهة برمجة التطبيقات التي تريد الاتصال بها. على سبيل المثال، لاستدعاء واجهة برمجة التطبيقات Drive API:

   $drive = new Google\Service\Drive($client);

3. يمكنك إرسال طلبات إلى خدمة واجهة برمجة التطبيقات باستخدام واجهة برمجة التطبيقات التي يوفّرها عنصر الخدمة. على سبيل المثال، لعرض الملفات في Google Drive للمستخدم الذي تمّت مصادقة هويته:

   $files = $drive->files->listFiles(array());

Python

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

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

   from googleapiclient.discovery import build
   
   drive = build('drive', 'v2', credentials=credentials)

2. يمكنك إرسال طلبات إلى خدمة واجهة برمجة التطبيقات باستخدام الواجهة التي يوفّرها عنصر الخدمة. على سبيل المثال، لعرض الملفات في Google Drive للمستخدم الذي تمّت مصادقة هويته:

   files = drive.files().list().execute()

Ruby

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

1. أنشئ عنصر خدمة لواجهة برمجة التطبيقات التي تريد الاتصال بها. على سبيل المثال، لاستدعاء الإصدار 3 من Drive API:

   drive = Google::Apis::DriveV3::DriveService.new

2. اضبط بيانات الاعتماد في الخدمة:

   drive.authorization = credentials

3. يمكنك إرسال طلبات إلى خدمة واجهة برمجة التطبيقات باستخدام الواجهة المقدَّمة من عنصر الخدمة. على سبيل المثال، لعرض الملفات في Google Drive للمستخدم الذي تمّت مصادقة هويته:

   files = drive.list_files

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

files = drive.list_files(options: { authorization: credentials })

Node.js

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

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

// Example of using Google Drive API to list filenames in user's Drive.
const drive = google.drive('v3');
drive.files.list({
  auth: oauth2Client,
  pageSize: 10,
  fields: 'nextPageToken, files(id, name)',
}, (err1, res1) => {
  if (err1) return console.log('The API returned an error: ' + err1);
  const files = res1.data.files;
  if (files.length) {
    console.log('Files:');
    files.map((file) => {
      console.log(`${file.name} (${file.id})`);
    });
  } else {
    console.log('No files found.');
  }
});

HTTP/REST

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

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

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

قد يبدو طلب البيانات من نقطة نهاية drive.files (Drive Files API) باستخدام عنوان HTTP Authorization: Bearer على النحو التالي. يُرجى العِلم أنّك بحاجة إلى تحديد رمز الدخول الخاص بك:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

أمثلة على curl

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

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

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

مثال كامل

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

PHP

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

1. في API Console، أضِف عنوان URL للجهاز المحلي إلى قائمة عناوين URL لإعادة التوجيه. على سبيل المثال، أضِف http://localhost:8080.
2. أنشئ دليلاً جديدًا وانتقِل إليه. على سبيل المثال:

   mkdir ~/php-oauth2-example
   cd ~/php-oauth2-example

3. ثبِّت مكتبة عميل واجهة برمجة التطبيقات للغة PHP باستخدام Composer:

   composer require google/apiclient:^2.15.0

4. أنشئ الملفَّين index.php وoauth2callback.php باستخدام المحتوى التالي.
5. شغِّل المثال باستخدام خادم ويب الاختبار المضمّن في 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']);
  
  // Check if user granted Drive permission
  if ($_SESSION['granted_scopes_dict']['Drive']) {
    echo "Drive feature is enabled.";
    echo "</br>";
    $drive = new Drive($client);
    $files = array();
    $response = $drive->files->listFiles(array());
    foreach ($response->files as $file) {
        echo "File: " . $file->name . " (" . $file->id . ")";
        echo "</br>";
    }
  } else {
    echo "Drive feature is NOT enabled.";
    echo "</br>";
  }

   // Check if user granted Calendar permission
  if ($_SESSION['granted_scopes_dict']['Calendar']) {
    echo "Calendar feature is enabled.";
    echo "</br>";
  } else {
    echo "Calendar feature is NOT enabled.";
    echo "</br>";
  }
}
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\Drive::DRIVE_METADATA_READONLY, Google\Service\Calendar::CALENDAR_READONLY]);

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

  // Determine which scopes user granted and build a dictionary
  $granted_scopes_dict = [
    'Drive' => str_contains($granted_scopes, Google\Service\Drive::DRIVE_METADATA_READONLY),
    'Calendar' => str_contains($granted_scopes, Google\Service\Calendar::CALENDAR_READONLY)
  ];
  $_SESSION['granted_scopes_dict'] = $granted_scopes_dict;
  
  $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 هذا، من المفترض أن تظهر لك خمسة روابط:

• طلب بيانات من واجهة برمجة تطبيقات Drive: يشير هذا الرابط إلى صفحة تحاول تنفيذ نموذج طلب واجهة برمجة التطبيقات في حال منح المستخدمين الإذن. ويبدأ عملية التفويض إذا لزم الأمر. في حال نجاح العملية، ستعرض الصفحة استجابة واجهة برمجة التطبيقات.
• صفحة وهمية للاتصال بـ Calendar API: يشير هذا الرابط إلى صفحة وهمية تحاول تنفيذ نموذج طلب Calendar API إذا منح المستخدمون الإذن. إذا لزم الأمر، يبدأ مسار التفويض. في حال نجاح العملية، ستعرض الصفحة استجابة واجهة برمجة التطبيقات.
• اختبار عملية المصادقة مباشرةً: يشير هذا الرابط إلى صفحة تحاول توجيه المستخدم من خلال عملية المصادقة. يطلب التطبيق إذنًا للقيام بما يلي: إرسال طلبات مفوَّضة لواجهات برمجة التطبيقات نيابةً عن المستخدم
• إبطال بيانات الاعتماد الحالية: يشير هذا الرابط إلى صفحة تُبطل الأذونات التي منحها المستخدم للتطبيق.
• محو بيانات اعتماد جلسة 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/drive.metadata.readonly',
          'https://www.googleapis.com/auth/calendar.readonly']
API_SERVICE_NAME = 'drive'
API_VERSION = 'v2'

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('/drive')
def drive_api_request():
  if 'credentials' not in flask.session:
    return flask.redirect('authorize')

  features = flask.session['features']

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

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

    files = drive.files().list().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(**files)
  else:
    # User didn't authorize read-only Drive activity permission.
    # Update UX and application accordingly
    return '<p>Drive feature is not enabled.</p>'

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

      features = flask.session['features']

      if features['calendar']:
        # User authorized Calendar read permission.
        # Calling the APIs, etc.
        return ('<p>User granted the Google Calendar read permission. '+
                'This sample code does not include code to call Calendar</p>')
      else:
        # User didn't authorize Calendar read permission.
        # Update UX and application accordingly
        return '<p>Calendar feature is not enabled.</p>'

@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
  
  credentials = credentials_to_dict(credentials)
  flask.session['credentials'] = credentials

  # Check which scopes user granted
  features = check_granted_scopes(credentials)
  flask.session['features'] = features
  return flask.redirect('/')
  

@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 check_granted_scopes(credentials):
  features = {}
  if 'https://www.googleapis.com/auth/drive.metadata.readonly' in credentials['granted_scopes']:
    features['drive'] = True
  else:
    features['drive'] = False

  if 'https://www.googleapis.com/auth/calendar.readonly' in credentials['granted_scopes']:
    features['calendar'] = True
  else:
    features['calendar'] = False

  return features

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 Google API Console.
  app.run('localhost', 8080, debug=True)

Ruby

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

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

require 'google/apis/drive_v3'
require 'google/apis/calendar_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 two non-Sign-In scopes: Read-only Drive activity and Google Calendar.
  scope = ['Google::Apis::DriveV3::AUTH_DRIVE_METADATA_READONLY',
           'Google::Apis::CalendarV3::AUTH_CALENDAR_READONLY']

  # 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 the request. Now, check which scopes were granted.
  if credentials.scope.include?(Google::Apis::DriveV3::AUTH_DRIVE_METADATA_READONLY)
    # User authorized read-only Drive activity permission.
    # Example of using Google Drive API to list filenames in user's Drive.
    drive = Google::Apis::DriveV3::DriveService.new
    files = drive.list_files(options: { authorization: credentials })
    "<pre>#{JSON.pretty_generate(files.to_h)}</pre>"
  else
    # User didn't authorize read-only Drive activity permission.
    # Update UX and application accordingly
  end

  # Check if user authorized Calendar read permission.
  if credentials.scope.include?(Google::Apis::CalendarV3::AUTH_CALENDAR_READONLY)
    # User authorized Calendar read permission.
    # Calling the APIs, etc.
  else
    # User didn't authorize Calendar read permission.
    # Update UX and application accordingly
  end
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

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

1. في API Console، أضِف عنوان URL الخاص بالجهاز المحلي إلى قائمة عناوين URL لإعادة التوجيه. على سبيل المثال، أضِف http://localhost.
2. تأكَّد من تثبيت إصدار LTS قيد الصيانة أو إصدار LTS نشط أو الإصدار الحالي من Node.js.
3. أنشئ دليلاً جديدًا وانتقِل إليه. على سبيل المثال:

   mkdir ~/nodejs-oauth2-example
   cd ~/nodejs-oauth2-example

4. ثبِّت مكتبة برمجيّات واجهة برمجة التطبيقات في Google لنظام Node.js باستخدام npm:

   npm install googleapis

5. أنشئ الملفات main.js باستخدام المحتوى التالي.
6. شغِّل المثال:

   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 two non-Sign-In scopes: Read-only Drive activity and Google Calendar.
const scopes = [
  'https://www.googleapis.com/auth/drive.metadata.readonly',
  'https://www.googleapis.com/auth/calendar.readonly'
];

/* 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;
      
      // User authorized the request. Now, check which scopes were granted.
      if (tokens.scope.includes('https://www.googleapis.com/auth/drive.metadata.readonly'))
      {
        // User authorized read-only Drive activity permission.
        // Example of using Google Drive API to list filenames in user's Drive.
        const drive = google.drive('v3');
        drive.files.list({
          auth: oauth2Client,
          pageSize: 10,
          fields: 'nextPageToken, files(id, name)',
        }, (err1, res1) => {
          if (err1) return console.log('The API returned an error: ' + err1);
          const files = res1.data.files;
          if (files.length) {
            console.log('Files:');
            files.map((file) => {
              console.log(`${file.name} (${file.id})`);
            });
          } else {
            console.log('No files found.');
          }
        });
      }
      else
      {
        // User didn't authorize read-only Drive activity permission.
        // Update UX and application accordingly
      }

      // Check if user authorized Calendar read permission.
      if (tokens.scope.includes('https://www.googleapis.com/auth/calendar.readonly'))
      {
        // User authorized Calendar read permission.
        // Calling the APIs, etc.
      }
      else
      {
        // User didn't authorize Calendar read permission.
        // Update UX and application accordingly
      }
    }
  });

  // 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 two non-Sign-In scopes: Read-only Drive activity and Google Calendar.
SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly'

# 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: 
    # User authorized the request. Now, check which scopes were granted.
    if 'https://www.googleapis.com/auth/drive.metadata.readonly' in credentials['scope']:
      # User authorized read-only Drive activity permission.
      # Example of using Google Drive API to list filenames in user's Drive.
      headers = {'Authorization': 'Bearer {}'.format(credentials['access_token'])}
      req_uri = 'https://www.googleapis.com/drive/v2/files'
      r = requests.get(req_uri, headers=headers).text
    else:
      # User didn't authorize read-only Drive activity permission.
      # Update UX and application accordingly
      r = 'User did not authorize Drive permission.'

    # Check if user authorized Calendar read permission.
    if 'https://www.googleapis.com/auth/calendar.readonly' in credentials['scope']:
      # User authorized Calendar read permission.
      # Calling the APIs, etc.
      r += 'User authorized Calendar permission.'
    else:
      # User didn't authorize Calendar read permission.
      # Update UX and application accordingly
      r += 'User did not authorize Calendar permission.'

  return r

@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 Drive. سيجد معظم المستخدمين أنّه من الطبيعي ألا يُطلب منهم منح إذن الوصول إلى Google Drive إلا في الوقت الذي يحتاج فيه التطبيق إلى ذلك.

في هذه الحالة، قد يطلب التطبيق نطاقَي openid و profile في وقت تسجيل الدخول لإجراء عملية تسجيل الدخول الأساسية، ثم يطلب في وقت لاحق نطاق https://www.googleapis.com/auth/drive.file في وقت أول طلب لحفظ ملف ترشيح.

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

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

• يمكن استخدام الرمز المميّز للوصول إلى الموارد التي تتوافق مع أيّ من النطاقات المضمّنة في الإذن الجديد المجمّع.
• عند استخدام الرمز المميّز لإعادة التحميل للتفويض المجمّع من أجل الحصول على رمز مميّز للوصول، يمثّل رمز الوصول التفويض المجمّع ويمكن استخدامه لأي من قيم 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

GET https://accounts.google.com/o/oauth2/v2/auth?
  client_id=your_client_id&
  response_type=code&
  state=state_parameter_passthrough_value&
  scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.readonly&
  redirect_uri=https%3A//oauth2.example.com/code&
  prompt=consent&
  include_granted_scopes=true

إعادة تحميل رمز دخول (الوصول بلا إنترنت)

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

• في حال استخدام مكتبة عميل واجهة برمجة تطبيقات Google، يُعيد عنصر العميل تحميل الرمز المميّز للوصول حسب الحاجة ما دام قد تم ضبط هذا العنصر للوصول بلا إنترنت.
• إذا كنت لا تستخدم مكتبة عملاء، عليك ضبط مَعلمة طلب البحث access_type HTTP على offline عند إعادة توجيه المستخدم إلى خادم OAuth 2.0 من Google. في هذه الحالة، يعرض خادم التفويض في Google رمزًا مميّزًا لإعادة التحميل عند استبدال رمز تفويضبرمز دخول. بعد ذلك، إذا انتهت صلاحية رمز الوصول (أو في أي وقت آخر)، يمكنك استخدام رمز مميز لإعادة التحميل للحصول على رمز وصول جديد.

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

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

PHP

إذا كان تطبيقك يحتاج إلى الوصول إلى واجهة برمجة تطبيقات Google بلا إنترنت، اضبط نوع وصول عميل واجهة برمجة التطبيقات على 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')

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

Ruby

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

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

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

Node.js

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

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
});

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

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

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	معرِّف العميل الذي تم الحصول عليه من API Console.
client_secret	سر العميل الذي تم الحصول عليه من API Console
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 https://www.googleapis.com/auth/calendar.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

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