Рекомендации по интеграции

Это пошаговое руководство поможет вам принять решения по всем основным вопросам интеграции.

Войти через Google в абстрактном виде

Ниже приведены общие шаги для входа/регистрации пользователей на вашем веб-сайте.

  1. Пользователи входят на сайт Google.

    Чтобы функция «Вход через Google» работала, в браузере должен быть активный сеанс Google. Функция One Tap и автоматический вход срабатывают только в том случае, если пользователи выполнили вход в Google перед загрузкой ваших веб-страниц. Этот шаг не является обязательным для процесса кнопки «Войти с помощью Google», поскольку пользователям предлагается войти в Google при нажатии кнопки.

  2. Пользователи просматривают ваши веб-страницы, на которых встроены кнопки «Одно касание», «Автоматический вход» или «Войти через Google».

  3. Пользователи взаимодействуют с One Tap, кнопкой «Войти через Google» и последующими процессами взаимодействия с пользователем, чтобы:

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

    Если в браузере есть только один активный сеанс Google,

    • One Tap автоматически выбирает единственный сеанс и, таким образом, пропускает страницу выбора учетной записи.
    • Кнопка «Войти через Google» остается на странице выбора учетной записи, что позволяет пользователям при необходимости добавлять новый сеанс Google.

    Если выбранная учетная запись Google ранее не использовалась на вашем веб-сайте или разрешение было отозвано, отобразится страница согласия.

    Войти с помощью кнопки согласия Google

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

  4. Учетные данные веб-токена JSON (также называемые токеном идентификатора), содержащие имя пользователя, адрес электронной почты и изображение профиля, передаются с помощью обработчика обратного вызова JavaScript или отправки сообщения в вашу серверную службу.

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

  5. На стороне вашего сервера учетные данные JWT, выданные Google, проверяются и используются для создания новой учетной записи или установления сеанса с аутентификацией на вашем веб-сайте.

    Вы будете управлять статусом входа пользователя на своем веб-сайте.

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

Таким образом, как и вход в систему с использованием пароля, «Вход через Google» предоставляет еще один способ аутентификации пользователей в Интернете . Вход через Google не предоставляет никаких функций для управления сеансами на вашем веб-сайте после аутентификации.

Доступ к API и сервисам Google

Хотя вы интегрировали API аутентификации, как описано выше, вам также может потребоваться интегрировать API авторизации , если вашему сайту требуется доступ к API и службам Google от имени аутентифицированных пользователей. В то время как аутентификация предоставляет вашему сайту токены идентификатора для аутентификации пользователей, авторизация предоставляет вашему сайту (отдельные) токены доступа и разрешения на использование API и сервисов Google. Дополнительную информацию см. в разделе Авторизация в Интернете .

Разделение UX для аутентификации и авторизации

Если вашему веб-сайту необходимо вызывать API аутентификации и авторизации, вы должны вызывать их отдельно в разные моменты. См . Разделение моментов аутентификации и авторизации .

Если ваш веб-сайт ранее запрашивал токены аутентификации и авторизации одновременно, при использовании библиотеки JavaScript Google Identity Services вам необходимо настроить свой UX, чтобы отделить момент аутентификации от момента авторизации.

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

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

  1. Рефакторинг UX, чтобы разделить моменты аутентификации и авторизации.

  2. Перейдите на библиотеку JavaScript Google Identity Services.

HTML API против JavaScript API

Вы можете использовать HTML API или JavaScript API для интеграции кнопок «Одно касание», «Автоматический вход» или «Войти через Google» на свои веб-страницы.

Благодаря HTML API у вас есть больше встроенных функций. Например,

  • Отображение одним нажатием или кнопкой «Войти через Google» при загрузке страницы.
  • Отправьте возвращенные учетные данные в конечную точку на стороне сервера, которая указана атрибутом data-login_uri , после выполнения UX в одно касание, автоматического входа или всплывающего окна или перенаправления кнопки.
  • Предотвратите атаки CSRF с помощью двойного файла cookie .
  • Используйте генератор кода для создания HTML-кода, а затем просто скопируйте его на свои HTML-страницы.

С помощью HTML API вы также можете написать JavaScript для настройки поведения.

  • Вы можете написать свой собственный обработчик обратного вызова, а затем установить имя функции в атрибуте data-callback . Хорошим примером является использование XmlHttpRequest для отправки возвращенных учетных данных на ваш сервер, чтобы избежать перезагрузки страницы, вызванной отправкой сообщения по умолчанию.

Благодаря API JavaScript у вас будет больше гибкости в некоторых сценариях, как показано ниже.

  • Отрисовка в одно касание и кнопка «Войти через Google» позже. Например, после того, как пользователи выбирают «Войти» в меню.
  • Вызов API несколько раз. Например, кнопку «Войти через Google» необходимо отображать каждый раз при отображении диалогового окна входа в систему.
  • Динамическое создание HTML-страниц, что затрудняет встраивание в них кода вызова API.
  • Библиотеку JavaScript Google Identity Services вы загружаете гораздо позже.

Код HTML API можно вызвать только один раз либо в событии загрузки страницы, либо в событии загрузки библиотеки JavaScript служб Google Identity Services, в зависимости от того, что наступит позже. Вам следует использовать JavaScript API, если поведение HTML API не соответствует вашим ожиданиям.

Не используйте API HTML с API JavaScript на одной и той же веб-странице для инициализации страницы или для отрисовки одним нажатием и кнопкой. Проверьте свой код, как HTML, так и JavaScript, на предмет мест, где они могут пересекаться. Обратите внимание на следующее:

  • Вы используете HTML API, если в вашем HTML-коде существует один или несколько элементов <div id='g_id_onload' ... ><id> или <div class='g_id_signin' ...></div> .
  • Вы используете API JavaScript, если в вашем коде JavaScript вызывается один или несколько методов в initialize() , prompt() или render() , независимо от того, встроены ли они или загружены из отдельного файла JavaScript.

Следующие API-интерфейсы JavaScript можно использовать независимо от инициализации или отрисовки одним касанием и кнопками; у них нет соответствующих HTML API:

Рекомендации по входу с помощью кнопки Google

Всплывающее окно против перенаправления

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

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

Пользовательский интерфейс всплывающего окна и перенаправления поддерживается кнопкой «Войти через Google». По умолчанию используется всплывающий интерфейс. Вы можете изменить UX, установив атрибут data-ux_mode .

Существуют некоторые различия между потоком перенаправления кнопки «Войти с помощью Google» и потоком перенаправления OAuth.

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

Для разработчиков, использующих HTML API, независимо от того, какой UX используется, учетные данные всегда передаются в data-login_uri с помощью метода POST и тех же параметров. Это позволяет переключать режим UX без других изменений кода. Для пользовательского интерфейса перенаправления data-login_uri необходимо добавить к URI авторизованного перенаправления для вашего клиента в консоли API Google .

Настройка кнопок

Использование собственной кнопки не поддерживается. Не существует API для программного запуска потока кнопок.

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

API рендеринга кнопок позволяет настроить внешний вид кнопки «Войти через Google». Рекомендуется использовать генератор кода для интерактивного проектирования кнопок. Даже если вы используете API JavaScript, вы можете сначала сгенерировать HTML-код, а затем скопировать его в соответствующие поля API JavaScript.

Не существует API, позволяющего веб-сайтам контролировать, следует ли использовать персонализированную информацию для отображения кнопок. Персонализированные кнопки отображаются, если соблюдены все условия. Более подробную информацию можно найти в разделе «Понять персонализированную кнопку» .

Вы можете разместить несколько кнопок на одной веб-странице. Генератор кода может каждый раз создавать только одну кнопку. Вы можете запустить его несколько раз и скопировать сгенерированный код <div class='g_id_signin' ...></div> на веб-страницу.

Рекомендации по рендерингу кнопок

Из соображений конфиденциальности персонализированная кнопка отображается в iframe из домена account.google.com. Загрузка iframe может занять много времени в медленной сети. Чтобы уменьшить эту проблему с задержкой, кнопки отображаются в два этапа следующим образом:

  1. Версия встроенной кнопки отображается в дереве DOM вашего веб-сайта. Это просто текстовая кнопка, никакой персонализированной информации использовать нельзя. Цель состоит в том, чтобы пользователи могли увидеть кнопку как можно скорее.
  2. В Google отправляется запрос iframe для загрузки кнопки iframe, которая может содержать персонализированную информацию. После загрузки кнопки iframe кнопка встроенной версии удаляется.

Ниже перечислены некоторые рекомендации по минимизации задержки при отображении кнопки «Войти через Google».

  • Загрузите библиотеку JavaScript Google Identity Services как можно раньше. Рассмотрите возможность загрузки библиотеки JavaScript раньше других крупных библиотек, особенно в мобильном Интернете.

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

Рекомендации по использованию One Tap

Автоматический вход

Отмена автоматического входа дает следующие преимущества.

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

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

Когда отображать интерфейс One Tap?

Благодаря HTML API функция One Tap всегда отображается при загрузке страницы. С помощью JavaScript

API, у вас есть возможность контролировать, когда отображается пользовательский интерфейс One Tap. Обратите внимание, что пользовательский интерфейс One Tap может не всегда отображаться после вызова API по некоторым причинам, описанным ниже.

  • В браузере нет активного сеанса Google.
  • Все активные сеансы Google отключены .
  • Идет восстановление.

Не пытайтесь отображать только пользовательский интерфейс One Tap при нажатии кнопки. Пользовательский интерфейс One Tap может не отображаться по вышеуказанным причинам, и у пользователей может быть некорректный пользовательский интерфейс, поскольку после действий пользователя ничего не отображается. В событии нажатия кнопки:

рекомендуемые

  • Покажите диалоговое окно входа с паролем и кнопкой «Войти через Google» и одновременно вызовите API One Tap. Это гарантирует, что пользователям всегда будет предложен тот или иной способ входа на ваш сайт.

Не рекомендуется

Одно касание в браузерах ITP

Из-за интеллектуальной системы предотвращения отслеживания (ITP) обычный интерфейс One Tap UX не работает в браузерах ITP, таких как Chrome в iOS, Safari и Firefox. Вместо этого в этих браузерах предоставляется другой пользовательский интерфейс, начинающийся со страницы приветствия.

При желании функцию One Tap UX в браузерах ITP можно отключить. Дополнительную информацию см. в разделе Поддержка One Tap в браузерах ITP .

Невозможно включить этот пользовательский интерфейс в браузерах, отличных от ITP, таких как Chrome на Android/macOS/Linux и Edge.

Отменить запрос, если пользователь уйдет

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

Рекомендуется оставлять приглашение One Tap открытым на рабочем столе в Интернете, поскольку размер экрана достаточно велик.

Измените положение One Tap UX

В настольной веб-версии вы можете изменить положение подсказки One Tap . Однако использовать эту функцию не рекомендуется, поскольку она не поддерживается федеративным управлением учетными данными в будущем выпуске.

Изменение контекста входа

One Tap должен быть частью более масштабного UX-процесса на вашем веб-сайте. По умолчанию пользовательский интерфейс One Tap используется в контексте входа. Язык пользовательского интерфейса содержит определенные слова, например «войти в систему». Вы можете изменить атрибут контекста, чтобы создать другой набор формулировок. Вы можете выбрать один из заголовков One Tap , который лучше всего соответствует вашему UX-процессу.

Контекст
signin «Войти через Google»
signup «Зарегистрируйтесь через Google»
use «Использовать с Google»

Прослушивание состояния пользовательского интерфейса One Tap

Чтобы легко интегрироваться в ваш более широкий UX-процесс, One Tap может уведомлять вас об изменении статуса пользовательского интерфейса . Однако эта функция не поддерживается в будущих выпусках федеративного управления учетными данными .

Одно касание между поддоменами

По умолчанию время восстановления One Tap и другие статусы отслеживаются для каждого источника. Если на вашем веб-сайте One Tap отображается на нескольких субдоменах, вам необходимо указать это в коде API.

Одно касание на статических HTML-страницах

По умолчанию библиотека ГИС предполагает, что ваши веб-страницы генерируются динамически. Ваш HTTP-сервер проверяет статус входа пользователя при создании HTML-кода.

  • Если ни один пользователь не вошел в систему, HTML-код One Tap должен быть включен в полученную страницу, чтобы активировать функцию One Tap, позволяющую пользователям входить на ваш веб-сайт.
  • Если пользователи уже вошли в систему, HTML-код One Tap не должен включаться в полученную страницу.

В этом случае ответственность за добавление или удаление кода One Tap HTML API лежит на вашем веб-сервере.

Код One Tap HTML API может работать по-другому, он предназначен для веб-сайтов, на которых размещено много статического HTML-контента. Вы всегда можете включить код One Tap HTML API в свои статические HTML-страницы и указать имя файла cookie сеанса, используемое на вашем веб-сайте.

  • Если файл cookie сеанса не существует, запускается поток One Tap.
  • Если файл cookie сеанса существует, поток One Tap пропускается.

В этом случае необходимость запуска потока One Tap определяется состоянием файлов cookie вашего сеанса, а не наличием кода HTML API One Tap на вашей веб-странице.

Интеграция на стороне сервера

После завершения процесса One Tap, автоматического входа в систему или пользовательского интерфейса кнопки «Войти с помощью Google» выдается токен идентификатора, который передается на ваш веб-сайт. Для аутентификации пользователя необходимо внести некоторые изменения на стороне сервера для получения и проверки токена идентификатора.

UX-соображения

Обычно вам необходимо добавить конечную точку HTTP в вашем собственном источнике для обработки ответов на стороне вашего сервера. Следующие факторы могут повлиять на конечный UX.

Фактический UX, который вы получаете, описан ниже.

  1. Для режима перенаправления кнопки «Войти через Google»:

    • Независимо от того, используется ли API HTML или API JavaScript, вам необходимо установить URI для входа. Невозможно использовать функцию обратного вызова JavaScript для обработки ответа, поскольку пользователи уже были перенаправлены с вашей веб-страницы.
    • Сводка по UX: после нажатия кнопки «Войти через Google» пользователи видят полностраничное перенаправление в пользовательский интерфейс Google для выбора и утверждения сеанса. После этого полностраничный POST отправляется на указанный вами URI входа.

  2. Для режима UX всплывающего окна «Одно касание» или «Войти с помощью Google», если используется API JavaScript или HTML API и предусмотрена функция обратного вызова JavaScript:

    • Ответы аутентификации передаются обратно в функцию обратного вызова JavaScript.
    • Краткое описание пользовательского интерфейса: над вашей веб-страницей отображается приглашение One Tap или всплывающее окно. После того как пользователи завершают работу с пользовательским интерфейсом в приглашении или всплывающем окне для выбора и утверждения сеанса, функция обратного вызова JavaScript получает ответы. Последующий UX определяется тем, как ваша функция обратного вызова отправляет ответы на ваш сервер.

  3. В противном случае (HTML API с регистром URI входа):

    • Ответы аутентификации передаются на URI входа.
    • Краткое описание UX: над вашей веб-страницей отображается приглашение One Tap или всплывающее окно. После того, как пользователи завершат работу с пользовательским интерфейсом в приглашении или всплывающем окне для выбора и утверждения сеанса, ответы на аутентификацию отправляются с использованием полностраничной отправки POST на указанный вами URL-адрес для входа.

Рекомендуется использовать единый способ отправки ответов One Tap и ответов кнопки «Войти через Google».

Соображения безопасности

Чтобы предотвратить атаки с подделкой межсайтовых запросов ,

  • Для отправки сообщений, инициированной клиентской библиотекой JavaScript службы идентификации Google, вы можете использовать встроенный шаблон двойной отправки файлов cookie. Дополнительные сведения см. в разделе Проверка токена Google ID на стороне сервера .
  • Для отправки в свой источник с помощью XmlHttpRequest вы можете использовать собственный HTTP-заголовок или другие меры безопасности, одобренные вашей командой безопасности.

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

Часто задаваемые вопросы (FAQ)

  • Доступна ли кнопка «Одно касание и вход с помощью Google» в веб-просмотрах?

    Нет. Из соображений безопасности пользователям не следует добавлять сеансы Google в веб-просмотр. Таким образом, ГИС отключены в веб-просмотрах, поскольку там не должно быть сеансов Google.

  • Могу ли я использовать собственную кнопку «Войти через Google»? Нет. Благодаря серверному потоку OAuth или более ранней версии библиотеки JavaScript для входа в Google проверяющие стороны могли использовать Рекомендации по брендингу для входа в систему для создания собственных версий кнопок входа в Google.

    Однако функция «Войти через Google» удалила эту функцию. Все кнопки «Войти с помощью Google» должны быть созданы библиотекой JavaScript Google Identity Services. Есть две причины этого изменения.

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

    Чтобы обеспечить соблюдение этого правила, библиотека JavaScript предоставляет только API для отображения кнопки, но не API для запуска процесса входа.

  • Что, если на моем веб-сайте доступна только кнопка «Одно касание», но нет кнопки «Войти с помощью Google»?

    Рекомендуется использовать на своем веб-сайте кнопку One Tap и кнопку «Войти через Google». Из-за экспоненциального охлаждения One Tap может отображаться не каждый раз. Если пользователи действительно хотят войти на ваш веб-сайт со своими учетными записями Google, они могут перейти в главное диалоговое окно входа в систему и войти в систему, нажав кнопку «Войти через Google». Успешный вход в систему с помощью кнопки «Войти через Google» очистит статус восстановления One Tap, и One Tap сможет отображаться при следующем входе в систему. Другие потоки кнопок от Google не могут очистить статусы восстановления One Tap , поскольку они находятся в разных двоичных файлах JavaScript.

    Если на вашем веб-сайте доступна только функция One Tap, но нет кнопки «Войти через Google», вы можете увидеть падение производительности вашего потока One Tap, поскольку статусы экспоненциального охлаждения не очищаются вовремя.

  • Когда мой код HTML API анализируется? Могу ли я позже изменить свой код HTML API?

    Библиотека JavaScript служб идентификации Google анализирует и выполняет ваш код HTML API либо в событии загрузки библиотеки JavaScript, либо в событии DomContentLoaded, в зависимости от того, что наступит позже .

    • Если событие DomContentLoaded инициируется при загрузке библиотеки JavaScript, ваш код HTML API анализируется и выполняется немедленно.
    • В противном случае библиотека JavaScript добавляет прослушиватель события DomContentLoaded. При срабатывании прослушиватель анализирует и выполняет ваш код HTML API.

    Также обратите внимание, что синтаксический анализ и выполнение кода HTML API выполняется один раз .

    • После анализа и выполнения любые последующие изменения в коде HTML API игнорируются.
    • Для разработчиков не существует API, позволяющего запускать процесс анализа или выполнения.