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

نمای کلی

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

مجوز گرانول چیست؟

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

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

دامنه های ورود و غیر ورود به سیستم

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

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

هنگامی که برنامه‌ها بیش از یک محدوده غیر ورود به سیستم درخواست می‌کنند، یک صفحه رضایت جزئیات برای کاربران نمایش داده می‌شود. کاربران می توانند مجوزهایی را که می خواهند تأیید کنند تا با برنامه به اشتراک بگذارند، انتخاب کنند. نمونه زیر نمونه ای از صفحه رضایت ریز است که درخواست دسترسی به پیام های 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 شامل Sign-In scope و non-Sign-In 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 شامل بیش از یک محدوده غیر ورود به سیستم است.

  یک درخواست نمونه زیر شامل دو محدوده غیر ورود به سیستم برای مشاهده فراداده 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 API Services: User Data Policy را مرور کنید و مطمئن شوید که از آنها پیروی می کنید.
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 برای درخواست کوچک‌ترین مجموعه دامنه‌های مورد نیاز و تابع hasPermissions برای بررسی اینکه کاربر هنگام درخواست مجوزهای جزئی به کدام حوزه‌ها اعطا کرده است استفاده کنید.

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

باید از 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 را نشان می دهد که دو محدوده غیر ورود به سیستم را درخواست می کند. کاربران صفحه رضایت ریز مجوز را مشاهده خواهند کرد.

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

...
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 API از برنامه های مبتنی بر سرور مرور کنید.

دسترسی فقط سمت مشتری

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

برنامه به روز شده خود را در مدیریت مجوزهای گرانول آزمایش کنید

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