איך לטפל בהרשאות מפורטות

סקירה כללית

הרשאות מפורטות מאפשרות לצרכנים לשלוט בצורה מדויקת יותר בנתוני החשבון שהם בוחרים לשתף עם כל אפליקציה. הן מועילות למשתמשים ולמפתחים כי הן מספקות יותר שליטה, שקיפות ואבטחה. המדריך הזה יעזור לכם להבין את השינויים והשלבים הנדרשים כדי לעדכן את האפליקציות שלכם כך שיטפלו בהרשאות גרנולריות.

מהי הרשאה מפורטת?

נניח שאתם מפתחים אפליקציה לפרודוקטיביות שמבקשת הרשאות גישה גם לאימייל וגם ליומן. יכול להיות שהמשתמשים שלכם ירצו להשתמש באפליקציה רק עבור יומן Google, ולא עבור Gmail. עם הרשאות OAuth מפורטות, משתמשים יכולים לבחור להעניק הרשאה ליומן Google בלבד, ולא ל-Gmail. האפשרות הזו מאפשרת למשתמשים להעניק גישה לנתונים ספציפיים, וכך מצמצמת את החשיפה של הנתונים, מחזקת את האמון ומעניקה למשתמשים שליטה על החיים הדיגיטליים שלהם תוך שמירה על הפרטיות. חשוב לתכנן את האפליקציה כך שתדע להתמודד עם תרחישים כאלה.

כשמבקשים יותר מהיקף אחד שלא קשור לכניסה

היקפים של כניסה לחשבון והיקפים ללא כניסה לחשבון

באפליקציות שמבקשות הרשאות גם לכניסה וגם לא לכניסה, המשתמשים רואים קודם את דף ההסכמה להיקפי ההרשאות לכניסה (email,‏ profile ו-openid). אחרי שהמשתמשים מסכימים לשתף את פרטי הזהות הבסיסיים שלהם (שם, כתובת אימייל ותמונת פרופיל), הם רואים מסך הסכמה להרשאות מפורטות לגבי היקפי ההרשאות שלא קשורים לכניסה. במקרה כזה, האפליקציה צריכה לבדוק אילו היקפי הרשאות המשתמשים העניקו לה, ולא להניח שהמשתמשים העניקו לה את כל היקפי ההרשאות שהיא ביקשה. בדוגמה הבאה, אפליקציית האינטרנט מבקשת את כל שלושת היקפי ההרשאות של הכניסה לחשבון ואת היקף ההרשאות של Google Drive שלא קשור לכניסה לחשבון. אחרי שהמשתמשים יאשרו את היקפי ההרשאות של הכניסה, הם יראו את מסך ההסכמה להרשאות המפורטות של Google Drive:

יותר מהיקף אחד שלא דורש כניסה

מסך הסכמה עם הרשאות מפורטות יוצג למשתמשים כשאפליקציות יבקשו יותר מהיקף אחד שאינו היקף כניסה. המשתמשים יכולים לבחור אילו הרשאות הם רוצים לאשר כדי לשתף עם האפליקציה. הדוגמה הבאה היא של מסך הסכמה עם הרשאות גרנולריות שבו מתבקשת גישה להודעות Gmail ולנתונים ביומן Google של המשתמש:

לא רלוונטי לאפליקציות שמבקשות רק היקפי הרשאות של כניסה (email,‏ profile ו-openid). המשתמשים מאשרים או דוחים את כל בקשת הכניסה. במילים אחרות, אם אפליקציות מבקשות רק היקפי הרשאות של כניסה לחשבון (אחד, שניים או שלושתם), מסך ההסכמה להרשאות המפורטות לא רלוונטי.

אם האפליקציה מבקשת רק היקף הרשאות אחד שלא קשור לכניסה לחשבון, מסך ההסכמה להרשאות המפורטות לא רלוונטי. במילים אחרות, המשתמשים מאשרים או דוחים את כל הבקשה, ואין תיבת סימון במסך ההסכמה. בטבלה הבאה מפורט מתי מוצג מסך ההסכמה להרשאות מפורטות.

איך קובעים אם האפליקציות מושפעות

צריך לבדוק היטב את כל הקטעים באפליקציה שבהם נעשה שימוש בנקודות הקצה של הרשאות Google OAuth 2.0 לבקשות הרשאה. שימו לב לאפליקציות שמבקשות כמה היקפי הרשאות, כי הן מציגות למשתמשים מסכי הסכמה עם הרשאות מפורטות. במקרים כאלה, חשוב לוודא שהקוד יכול לטפל במצב שבו המשתמשים מאשרים רק חלק מההיקפים.

איך קובעים אם האפליקציה משתמשת בכמה היקפי הרשאה

בודקים את קוד האפליקציה או את הקריאה היוצאת לרשת כדי לקבוע אם בקשות ההרשאה של OAuth 2.0 של Google שהאפליקציה שולחת יגרמו להצגת מסך ההסכמה להרשאות המפורטות.

בדיקת קוד האפליקציה

בודקים את החלקים בקוד האפליקציה שבהם מתבצעות קריאות לנקודות הקצה של הרשאות 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 מכיל יותר מהיקף אחד שאינו 'כניסה'.

  דוגמה לבקשה עם שני היקפי הרשאות שלא קשורים לכניסה לחשבון, לצורך הצגת המטא-נתונים של המשתמש ב-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 ומוודאים שאתם עומדים בדרישות שלה.
2. בקשה של היקפים ספציפיים שנדרשים למשימה. אתם חייבים לפעול בהתאם למדיניות OAuth 2.0 של Google, ולפי לבקש רק את היקפי ההרשאות שאתם צריכים. מומלץ להימנע מבקשת כמה היקפי הרשאות בכניסה, אלא אם זה חיוני לפונקציונליות העיקרית של האפליקציה. אם מבקשים כמה היקפי הרשאות ביחד, במיוחד ממשתמשים חדשים שלא מכירים את התכונות של האפליקציה, יכול להיות שיהיה להם קשה להבין למה נדרשות ההרשאות האלה. זה עלול לעורר חשד ולמנוע ממשתמשים להמשיך להשתמש באפליקציה שלכם.
3. מספקים למשתמשים הצדקה לפני שמבקשים מהם לאשר את בקשת ההרשאה. להסביר בצורה ברורה למה האפליקציה צריכה את ההרשאה המבוקשת, מה תעשו עם נתוני המשתמשים ואיך המשתמשים ירוויחו מאישור הבקשה. המחקר שלנו מצביע על כך שההסברים האלה מגבירים את האמון של המשתמשים ואת ההתעניינות שלהם.
4. משתמשים בהרשאה מצטברת בכל פעם שהאפליקציה מבקשת היקפי הרשאות, כדי להימנע מניהול של כמה אסימוני גישה.
5. בודקים אילו היקפי הרשאות המשתמשים העניקו. כשמבקשים כמה היקפי גישה בבת אחת, יכול להיות שהמשתמשים לא יאשרו את כל היקפי הגישה שהאפליקציה מבקשת. האפליקציה צריכה תמיד לבדוק אילו היקפי הרשאות המשתמש העניק, ולטפל בכל דחייה של היקפי הרשאות על ידי השבתת התכונות הרלוונטיות. פועלים בהתאם למדיניות Google בנושא OAuth 2.0 בנושא טיפול בהסכמה למספר היקפי הרשאות, ומבקשים מהמשתמשים להביע הסכמה רק אחרי שהם מציינים בבירור שהם רוצים להשתמש בתכונה הספציפית שדורשת את היקף ההרשאות.

עדכון האפליקציה כדי לטפל בהרשאות גרנולריות

אפליקציות ל-Android

כדאי לעיין במסמכי התיעוד של ערכות ה-SDK שבהן אתם משתמשים כדי ליצור אינטראקציה עם Google OAuth 2.0 ולעדכן את האפליקציה כך שתטפל בהרשאות גרנולריות בהתאם לשיטות המומלצות.

אם משתמשים ב-SDK של auth.api.signin מ-Play Services כדי ליצור אינטראקציה עם Google OAuth 2.0, אפשר להשתמש בפונקציה requestPermissions כדי לבקש את קבוצת היקפי ההרשאות הקטנה ביותר שנדרשת, ובפונקציה hasPermissions כדי לבדוק אילו היקפי הרשאות המשתמש העניק כשביקש הרשאות גרנולריות.

אפליקציות של תוספים ל-Chrome

כדי לעבוד עם Google OAuth 2.0 על סמך שיטות מומלצות, צריך להשתמש ב-Chrome Identity API.

בדוגמה הבאה אפשר לראות איך מטפלים בהרשאות גרנולריות בצורה נכונה.

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 Sign-In for iOS and 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 APIs מאפליקציות שמבוססות על שרתים.

גישה רק מצד הלקוח

• אם האפליקציות שלכם משתמשות בספריית JavaScript של Google Identity Services כדי ליצור אינטראקציה עם Google OAuth 2.0, כדאי לעיין במסמכי התיעוד האלה בנושא ניהול הרשאות גרנולריות.
• אם האפליקציות שלכם מבצעות קריאות ישירות באמצעות JavaScript לנקודות קצה של הרשאות OAuth 2.0 של Google, כדאי לעיין במסמכי התיעוד האלה בנושא טיפול בהרשאות גרנולריות.

בדיקת האפליקציה המעודכנת בנוגע לטיפול בהרשאות מפורטות

1. מתארים את כל המקרים שבהם המשתמשים יכולים להשיב לבקשות הרשאה ואת ההתנהגות הצפויה של האפליקציה. לדוגמה, אם המשתמש מאשר רק שניים מתוך שלושת היקפי ההרשאות המבוקשים, האפליקציה צריכה להתנהג בהתאם.
2. בודקים את האפליקציה עם הרשאות מפורטות מופעלות. יש שתי דרכים להפעיל הרשאות גרנולריות:
   1. בודקים את מסכי ההסכמה ל-OAuth 2.0 של האפליקציה כדי לראות אם הרשאות גרנולריות כבר מופעלות באפליקציה. אפשר גם ליצור מזהה לקוח חדש ל-Google OAuth 2.0 ל-Web, ל-Android או ל-iOS דרך מסוף Google Cloud למטרות בדיקה, כי הרשאה מפורטת תמיד מופעלת עבורם.
   2. מגדירים את הפרמטר enable_granular_consent לערך true כשקוראים לנקודות הקצה של ההרשאות ב-Google OAuth . חלק מה-SDK כוללים תמיכה מפורשת בפרמטר הזה. במקרים אחרים, כדאי לעיין במסמכים כדי להבין איך אפשר להוסיף את הפרמטר הזה ואת הערך שלו באופן ידני. אם ההטמעה שלכם לא תומכת בהוספת הפרמטר, תוכלו ליצור מזהה לקוח חדש של Google OAuth 2.0 ל-Web, ל-Android או ל-iOS דרך מסוף Google Cloud למטרות בדיקה בלבד, כפי שצוין בנקודה הקודמת.
3. כשבודקים את האפליקציה המעודכנת, צריך להשתמש בחשבון Google אישי (‎@gmail.com) ולא בחשבון Workspace. הסיבה לכך היא שאפליקציות של Workspace Enterprise עם הענקת הרשאות ברמת הדומיין או אפליקציות שמסומנות כמהימנות לא מושפעות כרגע מהשינויים בהרשאות המפורטות. לכן, יכול להיות שבדיקה באמצעות חשבון Workspace של הארגון לא תציג את מסך הבעת ההסכמה הפרטנית החדש כמו שרציתם.