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

סקירה כללית

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

מהי הרשאה ספציפית?

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

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

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

באפליקציות שמבקשות גם היקפי הרשאות לכניסה וגם היקפי הרשאות שלא קשורים לכניסה, המשתמשים רואים קודם את דף ההסכמה להיקפי הרשאות לכניסה (email,‏ profile ו-openid). אחרי שהמשתמשים מסכימים לשתף את פרטי הזהות הבסיסיים שלהם (שם, כתובת אימייל ותמונת פרופיל), הם רואים מסך הסכמה להרשאות פרטניות להיקפי ההרשאות שלא קשורים לכניסה. במקרה כזה, האפליקציה צריכה לבדוק אילו היקפי הרשאות המשתמשים נתנו, ולא להניח שהמשתמשים נותנים את כל היקפי ההרשאות שהיא מבקשת. בדוגמה הבאה, אפליקציית האינטרנט מבקשת את כל שלושת היקפי ההרשאות של הכניסה, והיקף הרשאות של Google Drive שלא קשור לכניסה. אחרי שהמשתמשים יאשרו את ההיקפים של הכניסה, יוצג להם מסך ההסכמה להרשאות פרטניות של 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 earlier.
    * 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
});

בדיקת קריאה יוצאת לרשת

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

• אפליקציית אינטרנט – בדיקת הפעילות ברשת ב-Chrome
• Android – בדיקת התנועה ברשת באמצעות Network Inspector
• אפליקציות Chrome
  • עוברים אל דף התוספים ל-Chrome.
  • מסמנים את התיבה מצב פיתוח בפינה השמאלית העליונה של דף התוספים.
  • בוחרים את התוסף שרוצים לעקוב אחריו.
  • לוחצים על הקישור דף רקע בקטע בדיקת תצוגות בדף התוסף.
  • תיבת הדו-שיח כלים למפתחים תיפתח, ותוכלו לעקוב אחרי התנועה ברשת בכרטיסייה "רשת".
• iOS – ניתוח תנועת HTTP באמצעות Instruments
• אפליקציות למחשב – משתמשים בכלי לתיעוד תעבורת נתונים ברשת שזמין למערכת ההפעלה שעבורה פותחה האפליקציה.

בזמן בדיקת הקריאות לרשת, חפשו בקשות שנשלחו לנקודות הקצה לאימות של Google OAuth ובדקו את הפרמטר scope.

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

• הפרמטר scope מכיל היקפי הרשאות לכניסה והיקפי הרשאות שלא לכניסה.

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

אפליקציות אינטרנט

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

גישה בצד השרת (אופליין)

כדי להשתמש במצב גישה בצד השרת (אופליין), צריך לבצע את הפעולות הבאות:

• מגדירים שרת ונקודת קצה שנגישה לכולם כדי לקבל את קוד ההרשאה.
• מגדירים את כתובת ה-URI להפניה אוטומטית של נקודת הקצה הציבורית בדף Clients במסוף Google Cloud.

בקטע הקוד הבא יש דוגמה ל-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 earlier
  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 the Google authorization server.
    if (req.url == '/') {
      res.writeHead(301, { "Location": authorizationUrl });
    }
    // Receive the callback from the Google authorization server.
    if (req.url.startsWith('/oauth2callback')) {
      // Handle the Google authorization 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 earlier
  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 the Google authorization server.
    if (req.url == '/') {
      res.writeHead(301, { "Location": authorizationUrl });
    }
    // Receive the callback from the Google authorization server.
    if (req.url.startsWith('/oauth2callback')) {
      // Handle the Google authorization 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 מאפליקציות שמבוססות על שרת.

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

• באפליקציות שמשתמשות בספריית JavaScript של Google Identity Services כדי לקיים אינטראקציה עם Google OAuth 2.0, כדאי לעיין במסמך התיעוד הזה בנושא טיפול בהרשאות פרטניות.
• באפליקציות שמבצעות קריאות ישירות באמצעות 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 למטרות בדיקה בלבד, כפי שצוין בנקודה הקודמת.

3. כשבודקים את האפליקציה המעודכנת, צריך להשתמש בחשבון Google אישי (‎@gmail.com) במקום בחשבון Workspace. הסיבה לכך היא שאפליקציות Workspace Enterprise עם הענקת גישה ברמת הדומיין או כאלה שמסומנות כמהימנות לא מושפעות כרגע מהשינויים בהרשאות הפרטניות. לכן, אם תבצעו בדיקה באמצעות חשבון Workspace מהארגון שלכם, יכול להיות שמסך ההסכמה הפרטנית החדש לא יוצג כמו שצריך.