Как обрабатывать детальные разрешения

Обзор

Благодаря детализированным разрешениям пользователи получают более точный контроль над тем, какие данные учетной записи они предоставляют каждому приложению. Это выгодно как пользователям, так и разработчикам, обеспечивая больший контроль, прозрачность и безопасность. Это руководство поможет вам понять необходимые изменения и шаги для успешного обновления ваших приложений для работы с детализированными разрешениями.

Что такое детализированные разрешения?

Представьте, что вы разрабатываете приложение для повышения производительности, которое запрашивает доступ как к электронной почте, так и к календарю. Ваши пользователи могут хотеть использовать приложение только для Google Календаря, но не для Gmail. Благодаря детализированным разрешениям OAuth пользователи могут выбрать, предоставлять ли доступ только к Google Календарю, но не к Gmail. Предоставляя пользователям доступ к конкретным данным, это минимизирует утечку данных, укрепляет доверие и дает пользователям контроль над своей цифровой жизнью, ставя во главу угла конфиденциальность. Важно разработать приложение таким образом, чтобы оно обрабатывало подобные сценарии.

Когда запрашивается более одной области действия, не связанной с входом в систему.

Области действия, связанные с авторизацией и без авторизации.

Для приложений, запрашивающих как доступ для авторизации, так и доступ без авторизации, пользователи сначала видят страницу согласия для доступа к данным для авторизации ( email , profile и openid ). После того, как пользователи дадут согласие на предоставление своей основной идентификационной информации (имя, адрес электронной почты и фотография профиля), они увидят подробный экран согласия на предоставление доступа к данным без авторизации. В этом случае приложение должно проверить, какие права доступа предоставлены пользователями, и не может предполагать, что пользователи предоставляют все запрошенные права доступа. В следующем примере веб-приложение запрашивает все три права доступа для авторизации и доступ без авторизации к Google Диску. После того, как пользователи дадут согласие на доступ к данным для авторизации, они увидят подробный экран согласия на предоставление доступа к Google Диску:

Более одной области действия, не связанной с входом в систему.

При запросе приложениями доступа к нескольким разрешениям, не относящимся к авторизации, пользователям будет отображаться подробный экран согласия на предоставление доступа. Пользователи могут выбрать, какие разрешения они хотят разрешить приложению. Ниже приведен пример подробного экрана согласия на предоставление доступа к сообщениям Gmail и данным Google Calendar пользователя:

Для приложений, запрашивающих только области авторизации ( 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 Диск:

  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 Диск и управления определенными файлами в Google Диск:

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 по обработке согласия на использование нескольких областей доступа и запрашивайте согласие у пользователя повторно только после того, как он четко указал на намерение использовать конкретную функцию, требующую данной области доступа.

Обновите приложение для обработки детальной настройки прав доступа.

Приложения для Android

Вам следует ознакомиться с документацией SDK, которые вы используете для взаимодействия с Google OAuth 2.0, и обновить ваше приложение, чтобы оно обрабатывало детализированные разрешения в соответствии с передовыми методами .

Если вы используете SDK auth.api.signin из Play Services для взаимодействия с Google OAuth 2.0, вы можете использовать функцию requestPermissions для запроса минимального набора необходимых областей действия (scopes) , а функцию 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 для 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);
}

Ознакомьтесь с руководством по разработке серверных веб-приложений , чтобы узнать, как получить доступ к API Google из серверных приложений.

Доступ только на стороне клиента

• Для приложений, использующих библиотеку JavaScript Google Identity Services для взаимодействия с Google OAuth 2.0, следует ознакомиться с этой документацией по управлению детализированными разрешениями.
• Для приложений, которые напрямую обращаются к точкам авторизации Google OAuth 2.0 с помощью JavaScript, следует ознакомиться с этой документацией по обработке детализированных разрешений.

Протестируйте обновленное приложение на предмет обработки детальных разрешений.

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 вашей организации новый экран детального согласия может отображаться не так, как предполагалось.