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

Обзор

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

Что такое гранулярное разрешение?

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

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

Android-приложения

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

Если вы используете auth.api.signin SDK из 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 для 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, вам следует ознакомиться с этой документацией по обработке детализированных разрешений.
• Для приложений, которые напрямую выполняют вызовы с использованием 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 вашей организации новый экран детального согласия может не отображаться, как предполагалось.