Обзор

Выберите путь интеграции

Выберите путь, который наилучшим образом соответствует вашим потребностям:

Путь	Лучше всего подходит для	Узнать больше
Универсальный протокол коммерции (UCP)	Торговцы и розничные продавцы.	Документация UCP
Стандартная привязка учетных записей	«Умный дом», телевидение и YouTube.	Документы

Примечание: Эти пути интеграции дополняют друг друга. Если вы внедряете UCP, мы рекомендуем ознакомиться как с руководством по связыванию идентификаторов UCP для получения информации о требованиях, специфичных для продукта, так и с данной документацией для получения подробной информации о реализации основного протокола OAuth.

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

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

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

Варианты использования

Вот несколько причин для внедрения функции привязки аккаунта Google:

• Делитесь данными пользователей со своей платформы с приложениями и сервисами Google.

• Интеграция с Google Shopping и платформами искусственного интеллекта (Поиск, Gemini) с использованием протокола Universal Commerce Protocol (UCP) .

• Воспроизводите видео и фильмы с помощью Google TV .

• Управляйте подключенными к Google Smart Home устройствами с помощью приложения Google Home и Google Ассистента: «Привет, Google, включи свет».

• Создавайте персонализированные для пользователей возможности и функциональность Google Ассистента с помощью диалоговых действий , например: «Привет, Google, закажи мой обычный заказ в Starbucks».

• Предоставьте пользователям возможность зарабатывать вознаграждения за просмотр соответствующих прямых трансляций на YouTube после привязки их учетной записи Google к учетной записи партнера по программе вознаграждений .

• При регистрации новых учетных записей автоматически заполняются данные, предоставленные с согласия пользователя из профиля учетной записи Google .

Возможности и требования

Приведенная ниже матрица определяет поддержку и рекомендации для каждого типа связей.

Поток связей	Стандартные характеристики	Функции UCP
App Flip	Рекомендуется	Рекомендуется
Упрощенная система ссылок	Рекомендуется	Рекомендуется
привязка OAuth	Обязательно (резервный вариант)	Обязательно (резервный вариант)
OAuth 2.1	Рекомендуется	Рекомендуется

• Повысьте уровень конфиденциальности пользователей, определив настраиваемые области доступа для обмена только необходимыми данными, и укрепите доверие пользователей, четко определив, как используются их данные.

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

Примечание: Большая часть документации по OAuth 2.0 для Google Identity Platform описывает, как вы можете авторизовать пользователей с помощью их учетных записей Google и получить разрешение на вызов API Google от их имени. Связывание учетных записей Google описывает обратный случай, когда пользователь сервиса Google может пройти аутентификацию на вашей платформе и вызвать API вашего сервиса. Если вы хотите использовать OAuth 2.0 для доступа к API Google, см. документацию по клиенту OAuth 2.0 .

Потоки связывания учетных записей

Существует 3 способа привязки учетной записи Google, все они основаны на OAuth и требуют от вас управления или контроля конечных точек авторизации и обмена токенами, совместимых с OAuth 2.0.

В процессе привязки вы выдаете Google токены доступа для отдельных учетных записей Google после получения согласия владельцев учетных записей на привязку своих аккаунтов и обмен данными.

привязка OAuth

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

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

Внимание: для потоков MCP, UCP и потоков, управляемых агентом, обязателен протокол OAuth 2.1, а неявный поток не поддерживается . Вместо этого используйте поток с кодом авторизации.

Примечание: Для всех интеграций, связанных с привязкой учетных записей, требуется внедрение OAuth-аутентификации , поскольку это резервный метод для потоков App Flip и Streamlined.

Рисунок 1. Привязка учетной записи на телефоне пользователя с использованием протокола OAuth.

Связывание приложений с функцией App Flip на основе OAuth («App Flip»)

Процесс аутентификации OAuth, который перенаправляет пользователей в ваше приложение для установления связи.

Функция App Flip Linking на основе OAuth помогает пользователям при переходе между вашими проверенными мобильными приложениями для Android или iOS и платформой Google ознакомиться с предлагаемыми изменениями в доступе к данным и дать согласие на привязку своей учетной записи на вашей платформе к своей учетной записи Google. Для включения функции App Flip ваш сервис должен поддерживать привязку OAuth или вход через Google с использованием кода авторизации на основе OAuth.

Приложение App Flip поддерживается как для Android , так и для iOS .

Как это работает:

Приложение Google проверяет, установлено ли ваше приложение на устройстве пользователя:

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

Рисунок 2. Привязка учетной записи на телефоне пользователя к приложению App Flip.

Упрощенная система связывания на основе OAuth («Упрощенная»).

Упрощенная система привязки «Вход через Google» на основе OAuth добавляет функцию «Вход через Google» поверх OAuth-связывания, позволяя пользователям завершить процесс привязки, не покидая интерфейс Google, тем самым уменьшая количество проблем и отказов. Упрощенная система привязки на основе OAuth обеспечивает наилучший пользовательский опыт благодаря бесшовному входу в систему, созданию учетной записи и ее привязке, объединяя функцию «Вход через Google» с OAuth-связыванием. Ваш сервис должен поддерживать авторизацию и конечные точки обмена токенами, соответствующие стандарту OAuth 2.0. Кроме того, ваша конечная точка обмена токенами должна поддерживать утверждения JSON Web Token (JWT) и реализовывать намерения check , create и get .

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

Как это работает:

Google подтверждает учетную запись пользователя и передает вам эту информацию:

• Если в вашей базе данных для пользователя существует учетная запись, пользователь успешно свяжет свою учетную запись Google со своей учетной записью в вашем сервисе.
• Если в вашей базе данных для пользователя нет учетной записи, он может либо создать новую учетную запись стороннего сервиса, используя предоставленную Google информацию: адрес электронной почты, имя и фотографию профиля , либо войти в систему и связать ее с другим адресом электронной почты (для этого потребуется войти в вашу службу с помощью аутентификации OAuth).

Рисунок 3. Привязка учетной записи на телефоне пользователя с помощью упрощенной привязки.

Какой алгоритм следует использовать?

Мы рекомендуем внедрить все варианты связывания, чтобы обеспечить пользователям наилучший опыт. Варианты «Упрощенное связывание» и «Переключение приложения» упрощают процесс, поскольку пользователи могут завершить его за очень короткое время. Вариант связывания через OAuth требует наименьших усилий и является хорошей отправной точкой, после чего можно добавлять другие варианты.

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

Работа с токенами

Функция привязки учетных записей Google основана на отраслевом стандарте OAuth 2.0.

Вы выдаете токены доступа Google для отдельных учетных записей Google после получения согласия владельцев учетных записей на привязку своих учетных записей и обмен данными.

Типы токенов

OAuth 2.0 использует строки, называемые токенами, для связи между пользовательским агентом, клиентским приложением и сервером OAuth 2.0.

При привязке учетной записи можно использовать три типа токенов OAuth 2.0:

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

• Токен доступа . Токен, предоставляющий владельцу доступ к ресурсу. Чтобы ограничить риски, которые могут возникнуть в результате потери этого токена, он имеет ограниченный срок действия, обычно истекающий через час или около того.

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

Обработка токенов

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

• Вы получаете запрос на получение нового токена доступа и выдаете новый токен доступа. Одновременно вы получаете запрос на доступ к ресурсу вашего сервиса, используя предыдущий, непросроченный токен доступа.
• Ваш ответ с токеном обновления еще не получен (или никогда не будет получен) компанией Google. Тем временем, ранее действительный токен обновления используется в запросе от Google.

Запросы и ответы могут поступать в любом порядке или не поступать вовсе из-за асинхронных служб, работающих в кластере, особенностей сети или других факторов.

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

• Принимайте действующие токены доступа, даже после выпуска более нового токена.
• Используйте альтернативы обновлению ротации токенов .
• Поддерживается одновременное использование нескольких действительных токенов доступа и обновления. В целях безопасности следует ограничить количество токенов и срок их действия.

Обработка заявок на техническое обслуживание и устранение неполадок

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

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

Внимание: во время технического обслуживания или сбоев не следует возвращать код ошибки 400 и тело запроса {"error": "invalid_grant"} . Это приведет к удалению ранее выданных токенов и потребует от пользователей повторной привязки учетных записей.

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

Рекомендации

Существует множество решений для минимизации воздействия на техническое обслуживание. Вот несколько вариантов, которые стоит рассмотреть:

• Сохраните существующий сервис и перенаправляйте ограниченное количество запросов на обновленный сервис. Переносите все запросы только после подтверждения ожидаемой функциональности.

• Сократите количество запросов токенов на период технического обслуживания:

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

  • Временно увеличьте срок действия токена доступа:

    1. Увеличьте срок действия токена до значений, превышающих период технического обслуживания.
    2. Увеличьте время ожидания вдвое по сравнению со сроком действия вашего токена доступа, что позволит пользователям обменивать токены с коротким сроком действия на токены с более длительным сроком действия.
    3. Перейдите в режим технического обслуживания.
    4. В ответ на запросы токенов следует отправлять код ошибки 503 и пустое тело запроса.
    5. Техническое обслуживание выходов.
    6. Уменьшить срок действия токена до нормального значения.

Постоянная связь

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

Для реализации постоянной привязки используйте подход «скользящего окна»: продлите срок действия существующего токена обновления вместо его замены (см. раздел 6 RFC 6749). Это предотвратит состояния гонки и непреднамеренное рассоединение, которые могут возникнуть, если новый токен обновления выпущен, но не был успешно получен или сохранен Google.

Зарегистрироваться в Google

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