نحوه رسیدگی به مجوزهای گرانول

نمای کلی

با مجوزهای جزئی، مصرف‌کنندگان کنترل دقیق‌تری بر داده‌های حساب کاربری که با هر برنامه به اشتراک می‌گذارند، خواهند داشت. این مجوزها با ارائه کنترل، شفافیت و امنیت بیشتر، هم به کاربران و هم به توسعه‌دهندگان سود می‌رسانند. این راهنما به شما کمک می‌کند تا تغییرات و مراحل لازم برای به‌روزرسانی موفقیت‌آمیز برنامه‌های خود برای مدیریت مجوزهای جزئی را درک کنید.

مجوز جزئی چیست؟

تصور کنید که شما یک برنامه کاربردی توسعه می‌دهید که هم به ایمیل و هم به تقویم نیاز دارد. کاربران شما ممکن است بخواهند از برنامه شما فقط برای تقویم گوگل استفاده کنند، اما نه برای جیمیل. با مجوزهای جزئی OAuth، کاربران می‌توانند فقط مجوز تقویم گوگل را اعطا کنند اما نه برای جیمیل. با اجازه دادن به کاربران برای دسترسی به داده‌های خاص، این امر افشای داده‌ها را به حداقل می‌رساند، اعتماد را تقویت می‌کند و به کاربران این امکان را می‌دهد که کنترل اولویت‌دار بر زندگی دیجیتال خود را بر اساس حریم خصوصی داشته باشند. طراحی برنامه شما برای مدیریت چنین سناریوهایی مهم است.

وقتی بیش از یک دامنه‌ی بدون ورود درخواست می‌شود

دامنه‌های ورود به سیستم و عدم ورود به سیستم

برای برنامه‌هایی که هم دامنه‌های ورود و هم دامنه‌های عدم ورود را درخواست می‌کنند، کاربران ابتدا صفحه رضایت برای دامنه‌های ورود ( email ، profile و openid ) را مشاهده می‌کنند. پس از اینکه کاربران برای به اشتراک گذاشتن اطلاعات هویتی اولیه خود (نام، آدرس ایمیل و عکس نمایه) رضایت خود را اعلام کردند، صفحه رضایت مجوز جزئی برای دامنه‌های عدم ورود را مشاهده خواهند کرد. در این حالت، برنامه باید بررسی کند که چه دامنه‌هایی توسط کاربران اعطا شده است و نمی‌تواند فرض کند که کاربران همه دامنه‌های درخواستی را اعطا می‌کنند. در مثال زیر، برنامه وب هر سه دامنه ورود و یک دامنه عدم ورود به سیستم گوگل درایو را درخواست می‌کند. پس از اینکه کاربران با دامنه‌های ورود موافقت کردند، صفحه رضایت مجوزهای جزئی را برای مجوز گوگل درایو مشاهده خواهند کرد:

بیش از یک محدوده بدون ورود

وقتی برنامه‌ها بیش از یک محدوده غیر از ورود به سیستم را درخواست می‌کنند، یک صفحه رضایت‌نامه مجوز جزئی به کاربران نمایش داده می‌شود. کاربران می‌توانند مجوزهایی را که می‌خواهند برای اشتراک‌گذاری با برنامه تأیید کنند، انتخاب کنند. در زیر نمونه‌ای از یک صفحه رضایت‌نامه مجوز جزئی که درخواست دسترسی به پیام‌های Gmail و داده‌های تقویم Google کاربر را دارد، آمده است:

برای برنامه‌هایی که فقط حوزه‌های ورود به سیستم ( email ، profile و openid ) را درخواست می‌کنند، صفحه رضایت مجوزهای جزئی قابل اجرا نیست. کاربران یا کل درخواست ورود را تأیید یا رد می‌کنند. به عبارت دیگر، اگر برنامه‌ها فقط حوزه‌های ورود به سیستم (یک، دو یا هر سه) را درخواست کنند، صفحه رضایت مجوزهای جزئی قابل اجرا نیست.

برای برنامه‌هایی که فقط یک محدوده غیر از ورود به سیستم را درخواست می‌کنند، صفحه رضایت مجوز جزئی قابل اجرا نیست . به عبارت دیگر، کاربران یا کل درخواست را تأیید یا رد می‌کنند و هیچ کادر تأییدی در صفحه رضایت وجود ندارد. جدول زیر خلاصه‌ای از زمان نمایش صفحه رضایت مجوزهای جزئی را نشان می‌دهد.

مشخص کنید که آیا برنامه‌های شما تحت تأثیر قرار گرفته‌اند یا خیر

تمام بخش‌های برنامه خود را که در آن‌ها از نقاط پایانی مجوز Google OAuth 2.0 برای درخواست‌های مجوز استفاده می‌شود، به طور کامل بررسی کنید. به بخش‌هایی که چندین دامنه درخواست می‌کنند توجه کنید، زیرا صفحات رضایت مجوز جزئی ارائه شده به کاربران را فعال می‌کنند. در چنین مواردی، مطمئن شوید که کد شما می‌تواند حالتی را که کاربران فقط برخی از دامنه‌ها را مجاز می‌کنند، مدیریت کند.

چگونه تشخیص دهیم که آیا برنامه ما از چندین scope استفاده می‌کند یا خیر

کد برنامه یا تماس شبکه خروجی خود را بررسی کنید تا مشخص شود که آیا درخواست‌های مجوز Google OAuth 2.0 که برنامه شما انجام می‌دهد، باعث نمایش صفحه رضایت مجوزهای جزئی می‌شود یا خیر.

کد برنامه خود را بررسی کنید

بخش‌هایی از کد برنامه خود را که در آن‌ها برای درخواست مجوز از کاربران، نقاط پایانی مجوز Google OAuth را فراخوانی می‌کنید، بررسی کنید. اگر از یکی از کتابخانه‌های کلاینت 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 شامل scopeهای ورود به سیستم و scopeهای غیر ورود به سیستم است.

  نمونه درخواست زیر شامل هر سه حوزه ورود به سیستم و یک حوزه غیر ورود به سیستم برای مشاهده ابرداده فایل‌های گوگل درایو کاربر است:

  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 شامل بیش از یک scope غیر از Sign-In است.

  یک درخواست نمونه زیر شامل دو محدوده غیر از ورود به سیستم برای مشاهده ابرداده‌های گوگل درایو کاربر و مدیریت فایل‌های خاص گوگل درایو است:

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. سیاست داده‌های کاربر: سرویس‌های API گوگل را بررسی کنید و مطمئن شوید که از آنها پیروی می‌کنید.
2. درخواست محدوده‌های خاصی که برای یک کار مورد نیاز هستند. شما باید از سیاست Google OAuth 2.0 مبنی بر اینکه فقط محدوده‌هایی را که نیاز دارید درخواست می‌کنید، پیروی کنید. باید از درخواست چندین محدوده در هنگام ورود به سیستم خودداری کنید، مگر اینکه برای عملکرد اصلی برنامه شما ضروری باشد. ترکیب چندین محدوده با هم، به ویژه برای کاربرانی که برای اولین بار با ویژگی‌های برنامه شما آشنا نیستند، می‌تواند درک نیاز به این مجوزها را برای آنها چالش برانگیز کند. این ممکن است باعث ایجاد هشدار شود و کاربران را از تعامل بیشتر با برنامه شما منصرف کند.
3. قبل از درخواست مجوز، توجیهی برای کاربران ارائه دهید . به طور واضح توضیح دهید که چرا برنامه شما به مجوز درخواستی نیاز دارد، با داده‌های کاربر چه کاری انجام خواهید داد و کاربر چگونه از تأیید درخواست بهره‌مند خواهد شد. تحقیقات ما نشان می‌دهد که این توضیحات اعتماد و تعامل کاربر را افزایش می‌دهد.
4. هر زمان که برنامه شما درخواست محدوده می‌کند، از مجوزدهی افزایشی استفاده کنید تا از مدیریت چندین توکن دسترسی جلوگیری شود.
5. بررسی کنید که کاربران کدام حوزه‌ها را اعطا کرده‌اند. هنگام درخواست چندین حوزه به طور همزمان، کاربران ممکن است به همه درخواست‌های برنامه شما اعطا نکنند. برنامه شما باید همیشه بررسی کند که کدام حوزه‌ها توسط کاربر اعطا شده است و با غیرفعال کردن ویژگی‌های مربوطه، هرگونه عدم پذیرش حوزه‌ها را مدیریت کند. از سیاست‌های Google OAuth 2.0 در مورد مدیریت رضایت برای حوزه‌های چندگانه پیروی کنید و فقط زمانی که کاربر به وضوح قصد استفاده از ویژگی خاصی را که به آن حوزه نیاز دارد، نشان داده است، دوباره از او رضایت بخواهید.

برنامه خود را برای مدیریت مجوزهای جزئی به‌روزرسانی کنید

اپلیکیشن‌های اندروید

شما باید مستندات SDK هایی را که برای تعامل با Google OAuth 2.0 استفاده می‌کنید، بررسی کنید و برنامه خود را برای مدیریت مجوزهای جزئی بر اساس بهترین شیوه‌ها ، به‌روزرسانی کنید.

اگر از auth.api.signin SDK از سرویس‌های Play برای تعامل با Google OAuth 2.0 استفاده می‌کنید، می‌توانید از تابع requestPermissions برای درخواست کوچکترین مجموعه از scopeهای مورد نیاز و از تابع hasPermissions برای بررسی scopeهایی که کاربر هنگام درخواست مجوزهای جزئی اعطا کرده است، استفاده کنید.

برنامه‌های افزودنی کروم

شما باید از API هویت کروم برای کار با Google OAuth 2.0 بر اساس بهترین شیوه‌ها استفاده کنید.

مثال زیر نحوه مدیریت صحیح مجوزهای جزئی را نشان می‌دهد.

مانیفست.json

فایل مانیفست مثال، دو محدوده‌ی غیر از ورود به سیستم را برای برنامه‌ی افزونه‌ی کروم تعریف می‌کند.

{
  "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 Sign-In برای iOS و macOS برای تعامل با Google OAuth 2.0 استفاده می‌کنید، باید مستندات مربوط به مدیریت مجوزهای جزئی را بررسی کنید.

برنامه‌های کاربردی وب

شما باید مستندات SDK هایی را که برای تعامل با Google OAuth 2.0 استفاده می‌کنید، بررسی کنید و برنامه خود را برای مدیریت مجوزهای جزئی بر اساس بهترین شیوه‌ها ، به‌روزرسانی کنید.

دسترسی از سمت سرور (آفلاین)

قطعه کد زیر یک مثال NodeJS را نشان می‌دهد که دو درخواست غیر از حوزه ورود (Sign-In) را ارائه می‌دهد. کاربران صفحه رضایت‌نامه مجوز را به صورت جزئی مشاهده خواهند کرد.

رویکرد نادرست

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

راهنمای برنامه وب سمت سرور را در مورد نحوه دسترسی به API های گوگل از برنامه های مبتنی بر سرور مرور کنید.

دسترسی فقط سمت کلاینت

• برای برنامه‌هایی که از کتابخانه جاوا اسکریپت Google Identity Services برای تعامل با Google OAuth 2.0 استفاده می‌کنند، باید این مستندات را در مورد مدیریت مجوزهای جزئی بررسی کنید.
• برای برنامه‌هایی که مستقیماً با استفاده از جاوا اسکریپت به نقاط پایانی مجوز Google OAuth 2.0 فراخوانی انجام می‌دهند، باید این مستندات را در مورد مدیریت مجوزهای جزئی بررسی کنید.

برنامه‌ی به‌روزرسانی‌شده‌ی خود را در مورد مدیریت مجوزهای جزئی آزمایش کنید

1. تمام مواردی را که کاربران می‌توانند به درخواست‌های مجوز پاسخ دهند و رفتار مورد انتظار از برنامه خود را شرح دهید . به عنوان مثال، اگر کاربر فقط دو مورد از سه محدوده درخواستی را مجاز کند، برنامه شما باید مطابق آن رفتار کند.
2. برنامه خود را با مجوز دانه‌ای فعال شده آزمایش کنید . دو راه برای فعال کردن مجوزهای دانه‌ای وجود دارد:
   1. صفحات رضایت OAuth 2.0 برنامه خود را بررسی کنید تا ببینید آیا مجوزهای جزئی از قبل برای برنامه شما فعال شده‌اند یا خیر. همچنین می‌توانید از طریق کنسول Google Cloud یک شناسه کلاینت Google OAuth 2.0 جدید برای وب، اندروید یا iOS ایجاد کنید تا آزمایش کنید، زیرا مجوزهای جزئی همیشه برای آنها فعال است.
   2. هنگام فراخوانی نقاط پایانی مجوز Google OAuth، پارامتر enable_granular_consent روی true تنظیم کنید. برخی از SDKها پشتیبانی صریحی از این پارامتر دارند. برای برخی دیگر، مستندات را بررسی کنید تا ببینید چگونه می‌توانید این پارامتر و مقدار آن را به صورت دستی اضافه کنید. اگر پیاده‌سازی شما از اضافه کردن پارامتر پشتیبانی نمی‌کند، می‌توانید از طریق کنسول Google Cloud یک شناسه کلاینت جدید Google OAuth 2.0 وب، اندروید یا iOS ایجاد کنید، فقط برای اهداف آزمایشی، همانطور که در نکته قبلی گفته شد.
3. هنگام آزمایش برنامه به‌روزرسانی‌شده خود، به جای حساب Workspace از یک حساب Google شخصی (@gmail.com) استفاده کنید. دلیل این امر این است که برنامه‌های Workspace Enterprise با تفویض اختیار در سطح دامنه یا علامت‌گذاری شده به عنوان Trusted، در حال حاضر تحت تأثیر تغییرات مجوزهای جزئی قرار نمی‌گیرند. بنابراین، آزمایش با یک حساب Workspace از سازمان شما ممکن است صفحه رضایت جزئی جدید را آنطور که در نظر گرفته شده است نشان ندهد.