كيفية التعامل مع الأذونات الدقيقة

نظرة عامة

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

ما هو الإذن الدقيق؟

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

عند طلب أكثر من نطاق واحد غير Sign-In

نطاقات تسجيل الدخول والنطاقات التي لا تتطلّب تسجيل الدخول

بالنسبة إلى التطبيقات التي تطلب نطاقات تسجيل الدخول وغير تسجيل الدخول، تظهر للمستخدمين أولاً صفحة الموافقة على نطاقات تسجيل الدخول (email وprofile وopenid). وبعد موافقة المستخدمين على مشاركة معلومات الهوية الأساسية (الاسم وعنوان البريد الإلكتروني وصورة الملف الشخصي)، ستظهر لهم شاشة موافقة على الأذونات الدقيقة لنطاقات غير تسجيل الدخول. في هذه الحالة، يجب أن يتحقّق التطبيق من النطاقات التي يمنحها المستخدمون، ولا يمكنه افتراض أنّ المستخدمين يمنحون جميع النطاقات المطلوبة. في المثال التالي، يطلب تطبيق الويب جميع نطاقات تسجيل الدخول ونطاقًا غير مرتبط بتسجيل الدخول في Google Drive. بعد موافقة المستخدمين على نطاقات تسجيل الدخول، ستظهر لهم شاشة الموافقة على الأذونات التفصيلية الخاصة بإذن Google Drive:

أكثر من نطاق واحد غير Sign-In

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

بالنسبة إلى التطبيقات التي تطلب نطاقات تسجيل الدخول فقط (email وprofile وopenid)، لا تنطبق شاشة الموافقة على الأذونات التفصيلية. يوافق المستخدمون على طلب تسجيل الدخول بأكمله أو يرفضونه. بمعنى آخر، إذا طلبت التطبيقات نطاقات تسجيل الدخول فقط (واحد أو اثنان أو ثلاثة)، لن تنطبق شاشة الموافقة على الأذونات التفصيلية.

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

تحديد ما إذا كانت تطبيقاتك متأثرة

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

كيفية تحديد ما إذا كان تطبيقك يستخدم نطاقات متعددة

افحص رمز تطبيقك أو طلب الشبكة الصادر لتحديد ما إذا كانت طلبات التفويض التي يرسلها تطبيقك إلى Google OAuth 2.0 ستؤدي إلى ظهور شاشة الموافقة على الأذونات الدقيقة.

فحص رمز التطبيق

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

const client = google.accounts.oauth2.initTokenClient({
  client_id: 'YOUR_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly \
  https://www.googleapis.com/auth/contacts.readonly',
  callback: (response) => {
    ...
  },
});

import google.oauth2.credentials
import google_auth_oauthlib.flow

# Use the client_secret.json file to identify the application requesting
# authorization. The client ID (from that file) and access scopes are required.
flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
    'client_secret.json',
    scopes=['https://www.googleapis.com/auth/calendar.readonly',
                    'https://www.googleapis.com/auth/contacts.readonly'])

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

/**
  * 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 read-only Calendar and Contacts.
const scopes = [
  'https://www.googleapis.com/auth/calendar.readonly',
  'https://www.googleapis.com/auth/contacts.readonly']
];

// Generate a url that asks permissions
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 best practices.
  include_granted_scopes: true
});

فحص مكالمة الشبكة الصادرة

أثناء فحص طلبات الشبكة، ابحث عن الطلبات المُرسَلة إلى نقاط نهاية التفويض في Google OAuth وافحص المَعلمة scope.

تتسبّب هذه القيم في عرض شاشة الموافقة على الأذونات التفصيلية.

• تحتوي المَعلمة scope على نطاقات تسجيل الدخول ونطاقات أخرى.

  يحتوي نموذج الطلب التالي على جميع نطاقات تسجيل الدخول ونطاق واحد غير مرتبط بتسجيل الدخول لعرض البيانات الوصفية لملفات المستخدم على Google Drive:

  https://accounts.google.com/o/oauth2/v2/auth?
  access_type=offline&
  scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.email%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.profile%20openid%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.metadata.readonly&
  include_granted_scopes=true&
  response_type=code&
  redirect_uri=YOUR_REDIRECT_URL&
  client_id=YOUR_CLIENT_ID

• تحتوي المَعلمة scope على أكثر من نطاق واحد غير Sign-In.

  يحتوي طلب النموذج التالي على نطاقَين غير مرتبطَين بميزة "تسجيل الدخول باستخدام Google" لعرض البيانات الوصفية لمستخدم Google Drive وإدارة ملفات معيّنة في Google Drive:

https://accounts.google.com/o/oauth2/v2/auth?
access_type=offline&
scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.metadata.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.file&
include_granted_scopes=true&
response_type=code&
redirect_uri=YOUR_REDIRECT_URL&
client_id=YOUR_CLIENT_ID

أفضل الممارسات للتعامل مع الأذونات الدقيقة

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

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

تعديل تطبيقك للتعامل مع الأذونات الدقيقة

تطبيقات Android

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

إذا كنت تستخدم حزمة تطوير البرامج (SDK) الخاصة بـ auth.api.signin من "خدمات Play" للتفاعل مع Google OAuth 2.0، يمكنك استخدام الدالة requestPermissions لطلب أصغر مجموعة من النطاقات اللازمة، والدالة hasPermissions للتحقّق من النطاقات التي منحها المستخدم عند طلب أذونات دقيقة.

تطبيقات إضافات Chrome

يجب استخدام Chrome Identity API للعمل مع Google OAuth 2.0 استنادًا إلى أفضل الممارسات.

يوضّح المثال التالي كيفية التعامل بشكل سليم مع الأذونات الدقيقة.

manifest.json

يعرِّف ملف البيان النموذجي نطاقَين غير مرتبطَين بميزة "تسجيل الدخول" لتطبيق إضافة Chrome.

{
  "name": "Example Chrome extension application",
  ...
  "permissions": [
      "identity"
    ],
  "oauth2" : {
      "client_id": "YOUR_CLIENT_ID",
      "scopes":["https://www.googleapis.com/auth/calendar.readonly",
                "https://www.googleapis.com/auth/contacts.readonly"]
  }
}

الأسلوب غير صحيح

...
document.querySelector('button').addEventListener('click', function () {
  chrome.identity.getAuthToken({ interactive: true },
      function (token) {
          if (token === undefined) {
            // User didn't authorize both scopes.
            // Updating the UX and application accordingly
            ...
          } else {
            // User authorized both or one of the scopes.
            // It neglects to check which scopes users granted and assumes users granted all scopes.

            // Calling the APIs, etc.
            ...
          }
      });
});

النهج الصحيح

...
document.querySelector('button').addEventListener('click', function () {
  chrome.identity.getAuthToken({ interactive: true, enableGranularPermissions: true },
      function (token, grantedScopes) {
          if (token === undefined) {
            // User didn't authorize any scope.
            // Updating the UX and application accordingly
            ...
          } else {
            // User authorized the request. Now, check which scopes were granted.
            if (grantedScopes.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
              ...
            }

            if (grantedScopes.includes('https://www.googleapis.com/auth/contacts.readonly'))
            {
              // User authorized Contacts read permission.
              // Calling the APIs, etc.
              ...
            }
            else
            {
              // User didn't authorize Contacts read permission.
              // Update UX and application accordingly
              ...
            }
          }
      });
});

تطبيقات iOS وiPadOS وmacOS

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

إذا كنت تستخدم مكتبة تسجيل الدخول باستخدام حساب Google لنظامَي التشغيل iOS وmacOS للتفاعل مع Google OAuth 2.0، عليك مراجعة المستندات حول كيفية التعامل مع الأذونات الدقيقة.

تطبيقات الويب

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

الوصول من جهة الخادم (بلا إنترنت)

يعرض مقتطف الرمز التالي مثالاً على NodeJS يطلب نطاقَين غير مرتبطَين بميزة "تسجيل الدخول باستخدام Google". سيظهر للمستخدمين شاشة طلب الموافقة على الأذونات التفصيلية.

الأسلوب غير صحيح

...
const oauth2Client = new google.auth.OAuth2(
  YOUR_CLIENT_ID,
  YOUR_CLIENT_SECRET,
  YOUR_REDIRECT_URL
);

// Access scopes for two non-Sign-In scopes - Google Calendar and Contacts
const scopes = [
  'https://www.googleapis.com/auth/contacts.readonly',
  'https://www.googleapis.com/auth/calendar.readonly'
];

// Generate a url that asks permissions for the Google Calendar and Contacts scopes
const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  // Pass in the scopes array defined above
  scope: scopes,
  // Enable incremental authorization. Recommended as best practices.
  include_granted_scopes: true
});

async function main() {
  const server = http.createServer(async function (req, res) {
    // Example on redirecting user to Google OAuth 2.0 server.
    if (req.url == '/') {
      res.writeHead(301, { "Location": authorizationUrl });
    }
    // Receive the callback from Google OAuth 2.0 server.
    if (req.url.startsWith('/oauth2callback')) {
      // Handle the Google OAuth 2.0 server response
      let q = url.parse(req.url, true).query;

      if (q.error) {
        // User didn't authorize both scopes.
        // Updating the UX and application accordingly
        ...
      } else {
        // User authorized both or one of the scopes.
        // It neglects to check which scopes users granted and assumes users granted all scopes.

        // Get access and refresh tokens (if access_type is offline)
        let { tokens } = await oauth2Client.getToken(q.code);
        // Calling the APIs, etc.
        ...
      }
    }
    res.end();
  }).listen(80);
}

النهج الصحيح

...
const oauth2Client = new google.auth.OAuth2(
  YOUR_CLIENT_ID,
  YOUR_CLIENT_SECRET,
  YOUR_REDIRECT_URL
);

// Access scopes for two non-Sign-In scopes - Google Calendar and Contacts
const scopes = [
  'https://www.googleapis.com/auth/contacts.readonly',
  'https://www.googleapis.com/auth/calendar.readonly'
];

// Generate a url that asks permissions for the Google Calendar and Contacts scopes
const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  // Pass in the scopes array defined above
  scope: scopes,
  // Enable incremental authorization. Recommended as best practices.
  include_granted_scopes: true,
  // Set to true to enable more granular permissions for Google OAuth 2.0 client IDs created before 2019.
  // No effect for newer Google OAuth 2.0 client IDs, since more granular permissions is always enabled for them.
  enable_granular_consent: true
});

async function main() {
  const server = http.createServer(async function (req, res) {
    // Redirect users to Google OAuth 2.0 server.
    if (req.url == '/') {
      res.writeHead(301, { "Location": authorizationUrl });
    }
    // Receive the callback from Google OAuth 2.0 server.
    if (req.url.startsWith('/oauth2callback')) {
      // Handle the Google OAuth 2.0 server response
      let q = url.parse(req.url, true).query;

      if (q.error) {
        // User didn't authorize both scopes.
        // Updating the UX and application accordingly
        ...
      } else {
        // Get access and refresh tokens (if access_type is offline)
        let { tokens } = await oauth2Client.getToken(q.code);
        oauth2Client.setCredentials(tokens);

        // User authorized the request. Now, check which scopes were granted.
        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.
          // Calling the APIs, etc.
          ...
        }

        // Check which scopes user granted the permission to application
        if (tokens.scope.includes('https://www.googleapis.com/auth/contacts.readonly'))
        {
          // User authorized Contacts read permission.
          // Calling the APIs, etc.
          ...
        }
        else
        {
          // User didn't authorize Contacts read permission.
          // Update UX and application accordingly
          ...
        }
      }
    }
    res.end();
  }).listen(80);
}

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

إذن الوصول من جهة العميل فقط

• بالنسبة إلى التطبيقات التي تستخدم مكتبة JavaScript الخاصة بخدمات Google Identity Services للتفاعل مع بروتوكول OAuth 2.0 من Google، عليك مراجعة هذا المستند حول كيفية التعامل مع الأذونات الدقيقة.
• بالنسبة إلى التطبيقات التي تجري طلبات مباشرة باستخدام JavaScript إلى نقاط نهاية تفويض Google OAuth 2.0، عليك مراجعة هذا المستند حول التعامل مع الأذونات الدقيقة.

اختبار تطبيقك المعدَّل في التعامل مع الأذونات الدقيقة

1. حدِّد جميع الحالات التي يمكن للمستخدمين فيها الاستجابة لطلبات الأذونات والسلوك المتوقّع من تطبيقك. على سبيل المثال، إذا وافق المستخدم على نطاقَين فقط من النطاقات الثلاثة المطلوبة، يجب أن يتصرّف تطبيقك وفقًا لذلك.
2. اختبِر تطبيقك مع تفعيل الأذونات الدقيقة. هناك طريقتان لتفعيل الأذونات الدقيقة:
   1. راجِع شاشات موافقة OAuth 2.0 في تطبيقك لمعرفة ما إذا كانت الأذونات الدقيقة مفعّلة لتطبيقك. يمكنك أيضًا إنشاء معرّف عميل جديد على Google OAuth 2.0 للويب أو Android أو iOS من خلال وحدة تحكّم Google Cloud لأغراض الاختبار، لأنّ الأذونات الدقيقة تكون مفعّلة دائمًا لهذه المعرّفات.
   2. اضبط المَعلمة enable_granular_consent على true عند طلب نقاط نهاية التفويض في Google OAuth. تتيح بعض حِزم تطوير البرامج (SDK) استخدام هذه المَعلمة بشكل صريح. بالنسبة إلى الآخرين، راجِع المستندات لمعرفة كيفية إضافة هذه المَعلمة وقيمتها يدويًا. إذا كان التنفيذ لا يتيح إضافة المَعلمة، يمكنك إنشاء معرّف عميل جديد على Google OAuth 2.0 للويب أو Android أو iOS من خلال Google Cloud Console لأغراض الاختبار فقط كما هو موضّح في النقطة السابقة.
3. عند اختبار تطبيقك المعدَّل، استخدِم حساب Google شخصيًا (@gmail.com) بدلاً من حساب Workspace. ويرجع ذلك إلى أنّ تطبيقات Workspace Enterprise التي تتضمّن تفويضًا على مستوى النطاق أو تم تصنيفها على أنّها موثوق بها لا تتأثر بالتغييرات التي تم إجراؤها على الأذونات الدقيقة في الوقت الحالي. لذلك، قد لا يؤدي الاختبار باستخدام حساب Workspace من مؤسستك إلى عرض شاشة الموافقة الجديدة التفصيلية على النحو المنشود.