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

Обзор

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

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

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

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

Области действия для входа и без входа

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

Несколько областей доступа, не связанных со входом

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

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

Если приложение запрашивает только одну область, не связанную со входом, то окно запроса доступа с выборочными разрешениями не показывается. Другими словами, пользователи либо одобряют, либо отклоняют весь запрос, и в окне запроса доступа нет флажка. В таблице ниже показано, когда отображается окно запроса доступа с детализированными разрешениями.

Как определить, затронуты ли ваши приложения

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

Как определить, использует ли ваше приложение несколько областей действия

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

Проверьте код приложения

Проверьте разделы кода приложения, в которых вы вызываете конечные точки авторизации Google OAuth, чтобы запросить разрешение у пользователей. Если вы используете одну из клиентских библиотек API Google, то можете найти области действия, запрашиваемые вашим приложением, на этапе инициализации клиента. Некоторые примеры показаны в следующем разделе. Чтобы определить, затронет ли это изменение ваше приложение, ознакомьтесь с документацией по 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 Диске:

  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. Ознакомьтесь с правилами в отношении пользовательских данных сервисов API Google и убедитесь, что вы их соблюдаете.
2. Запрашивайте только те области действия, которые необходимы для выполнения задачи. Вы должны соблюдать правила Google OAuth 2.0, согласно которым запрашивать можно только необходимые области действия. Не запрашивайте доступ к нескольким областям действия при входе, если это не требуется для работы основных функций приложения. Объединение нескольких областей действия, особенно для новых пользователей, незнакомых с функциями вашего приложения, может затруднить понимание необходимости этих разрешений. Это может вызвать у них подозрения и отбить желание пользоваться вашим приложением.
3. Предоставляйте пользователям обоснование, прежде чем запрашивать разрешение. Четко объясните, зачем приложению нужно запрашиваемое разрешение, что вы будете делать с данными пользователя и какую пользу он получит, если одобрит запрос. Наши исследования показывают, что такие объяснения повышают доверие и вовлеченность пользователей.
4. Используйте пошаговую авторизацию, когда приложение запрашивает области действия, чтобы не управлять несколькими токенами доступа.
5. Проверьте, какие области действия разрешили пользователи. Если вы запрашиваете несколько областей действия одновременно, пользователи могут предоставить не все из них. Приложение должно всегда проверять, какие области действия разрешены пользователем, и отключать соответствующие функции, если в доступе отказано. Следуйте правилам Google OAuth 2.0 в отношении обработки согласия для нескольких областей действия и запрашивайте согласие пользователя повторно, только если он явно выразил намерение использовать определенную функцию, для которой требуется область действия.

Обновите приложение, чтобы оно поддерживало детализированные разрешения

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

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

Если вы используете SDK auth.api.signin из сервисов Google Play для взаимодействия с 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 перенаправления общедоступной конечной точки на странице Клиенты в консоли 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);
}

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

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

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

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

1. Опишите все возможные ответы пользователей на запросы разрешений и ожидаемое поведение приложения. Например, если пользователь разрешает только две из трех запрошенных областей, ваше приложение должно вести себя соответствующим образом.

2. Протестируйте приложение с включенными детализированными разрешениями. Есть два способа включить детализированные разрешения:

   1. Проверьте, включены ли детализированные разрешения в окнах запроса доступа OAuth 2.0 вашего приложения. Вы также можете создать новый идентификатор клиента Google OAuth 2.0 для веб-приложений, Android или 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 с делегированием доступа к данным в домене или отмеченные как надежные. Поэтому при тестировании с аккаунтом Workspace из вашей организации новое окно запроса доступа может не показываться.