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

Обзор

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

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

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

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

Области действия для входа и другие области действия

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

Области действия для входа и другие области действия

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

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

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

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

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

Количество областей действия для входа Количество областей доступа, не связанных со входом в аккаунт Окно запроса доступа с выборочными разрешениями
1-3 0 Неприменимо
1-3 1+ Применимо
0 1 Неприменимо
0 2+ Применимо

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

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

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

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

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

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

Сервисы идентификации Google

Следующий фрагмент кода библиотеки JavaScript Сервисов идентификации Google инициализирует TokenClient с несколькими областями действия, не связанными со входом. Окно запроса доступа с детализированными разрешениями будет показываться, когда веб-приложение запрашивает авторизацию у пользователей.

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) => {
    ...
  },
});

Python

В следующем фрагменте кода для создания запроса на авторизацию используется модуль google-auth-oauthlib.flow. Параметр scope включает две области действия, не связанные со входом. Окно запроса доступа с детализированными разрешениями будет показываться, когда веб-приложение запрашивает авторизацию у пользователей.

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'
    ])

Node.js

Приведенный ниже фрагмент кода создает объект google.auth.OAuth2, который определяет параметры в запросе авторизации, параметр scope которого включает две области, не связанные со входом. Окно запроса доступа с детализированными разрешениями будет показываться, когда веб-приложение запрашивает авторизацию у пользователей.

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
});

Проверка исходящего сетевого вызова

Способ проверки сетевых вызовов зависит от типа приложения.

При проверке сетевых вызовов ищите запросы, отправленные на конечные точки авторизации 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"
      ]
  }
}

Неправильный подход

Все или ничего

Пользователи нажимают кнопку, чтобы запустить процесс авторизации. Фрагмент кода предполагает, что пользователям предлагается окно запроса доступа по принципу "все или ничего" для двух областей действия, указанных в файле manifest.json. Оно не проверяет, какие области действия разрешили пользователи.

oauth.js

...
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.
            ...
          }
      });
});

Правильный подход

Самые узкие области действия

Выберите минимальный набор необходимых областей действия

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

В этом примере предполагается, что обе области действия, объявленные в файле manifest.json, являются наименьшим необходимым набором областей действия. Файл oauth.js использует Chrome Identity API, чтобы инициировать процесс авторизации в Google. Рекомендуем включить детализированные разрешения, чтобы пользователи могли точнее настраивать доступ к данным для вашего приложения. Приложение должно правильно обрабатывать ответ пользователей, проверяя, какие области действия они разрешают.

oauth.js

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

Неправильный подход

Все или ничего

Пользователи перенаправляются на URL авторизации. В этом фрагменте кода предполагается, что пользователям показывается окно запроса доступа по принципу "все или ничего" для двух областей действия, указанных в массиве scopes. Оно не проверяет, какие области действия разрешили пользователи.

main.js

...
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);
}
Правильный подход

Наименьшая область действия

Выберите минимальный набор необходимых областей действия

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

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

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

main.js

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