Миграция с входа в Google

Это руководство поможет вам понять необходимые изменения и шаги для успешной миграции библиотек JavaScript с более ранней платформы Google Sign-In на новую библиотеку Google Identity Services для аутентификации .

Если ваш клиент использует клиентскую библиотеку Google API для JavaScript или другие более ранние библиотеки для авторизации , см. раздел «Переход на Google Identity Services» для получения дополнительной информации.

Аутентификация и авторизация

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

Как и предыдущая библиотека платформы Google Sign-In , новая библиотека Google Identity Services создана для поддержки как процессов аутентификации, так и авторизации.

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

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

Если ваш сценарий использования включает авторизацию, ознакомьтесь с разделом «Как работает авторизация пользователей» и «Переход на Google Identity Services», чтобы убедиться, что ваше приложение использует новые и улучшенные API.

Что изменилось?

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

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

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

• Возможность добавить авторизацию пользователей в статический контент вашего сайта, используя только HTML.
• Благодаря разделению аутентификации при входе в систему, авторизации и обмена пользовательскими данными, а также отсутствию сложности интеграции OAuth 2.0, необходимого для авторизации пользователей на вашем сайте, больше не требуется.
• Поддерживаются как всплывающие окна, так и режимы перенаправления, но инфраструктура Google OAuth 2.0 теперь перенаправляет на конечную точку входа на ваш бэкэнд-сервер.
• Объединение возможностей двух предыдущих библиотек JavaScript — Google Identity и Google API — в единую новую библиотеку.
• Теперь при обработке ответов на запросы авторизации вы можете сами решить, использовать ли Promise , а для упрощения процесса удалено косвенное обращение через функции-геттеры.

Пример миграции данных для входа в систему.

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

Библиотеки и конфигурация

Более ранняя библиотека платформы Google Sign-In: apis.google.com/js/platform.js и клиентская библиотека Google API для JavaScript : gapi.client , больше не требуются для аутентификации и авторизации пользователей. Они были заменены новой библиотекой JavaScript Google Identity Services: accounts.google.com/gsi/client .

Три предыдущих модуля JavaScript: api , client и platform используемые для входа в систему, загружаются с сайта apis.google.com . Чтобы помочь вам определить места, где может быть включена предыдущая библиотека на вашем сайте, обычно используются следующие:

• Кнопка входа по умолчанию загружает файл apis.google.com/js/platform.js .
• Графическое изображение пользовательской кнопки загружает файл apis.google.com/js/api:client.js , и
• Прямое использование gapi.client загружает apis.google.com/js/api.js .

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

• Ваши тестовые и производственные приложения используют отдельные проекты и имеют собственные идентификаторы клиентов.
• Тип идентификатора клиента OAuth 2.0 — «Веб-приложение», и
• HTTPS используется для авторизованных источников JavaScript и URI перенаправления.

Выявите затронутый код и протестируйте его.

Отладочный cookie может помочь обнаружить затронутый код и протестировать поведение после прекращения поддержки.

В больших или сложных приложениях может быть сложно найти весь код, затронутый устареванием модуля gapi.auth2 . Чтобы регистрировать в консоли использование функций, которые вскоре будут устаревать, установите значение cookie G_AUTH2_MIGRATION в informational . При желании добавьте двоеточие, за которым следует значение ключа, чтобы также записывать данные в хранилище сессий . После входа в систему и получения учетных данных просмотрите или отправьте собранные журналы на бэкэнд для последующего анализа. Например, informational:showauth2use сохраняет источник и URL-адрес в ключ хранилища сессий с именем showauth2use .

Чтобы проверить поведение приложения после прекращения поддержки модуля gapi.auth2 , установите значение cookie G_AUTH2_MIGRATION в enforced . Это позволит протестировать поведение после прекращения поддержки до наступления даты принудительного применения.

Возможные значения cookie G_AUTH2_MIGRATION :

• enforced не загружать модуль gapi.auth2 .
• informational Log use of deprexated capabilities to JS console. Also log into session storage when optional key name set: informational:key-name .

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

HTML и JavaScript

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

Более ранний способ

<html>
  <body>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <meta name="google-signin-client_id" content="YOUR_CLIENT_ID">
    <div class="g-signin2" data-onsuccess="handleCredentialResponse"></div>
  </body>
</html>

<html>
  <body>
    <script src="https://apis.google.com/js/platform.js" async defer></script>
    <meta name="google-signin-client_id" content="YOUR_CLIENT_ID">
    <div class="g-signin2" data-onsuccess="handleCredentialResponse"></div>
    <script>
      function handleCredentialResponse(googleUser) {
        ...
        var xhr = new XMLHttpRequest();
        xhr.open('POST', 'https://yourbackend.example.com/tokensignin');
        xhr.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
        xhr.onload = function() {
          console.log('Signed in as: ' + xhr.responseText);
        };
        xhr.send('idtoken=' + id_token);
      }
    </script>
  </body>
</html>

Новый способ

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

<html>
  <body>
    <script src="https://accounts.google.com/gsi/client" async defer></script>
    <div id="g_id_onload"
         data-client_id="YOUR_CLIENT_ID"
         data-callback="handleCredentialResponse">
    </div>
    <div class="g_id_signin" data-type="standard"></div>
  </body>
</html>

<html>
  <body>
    <script src="https://accounts.google.com/gsi/client" async defer></script>
    <div id="g_id_onload"
         data-client_id="YOUR_CLIENT_ID"
         data-ux_mode="redirect"
         data-login_uri="https://www.example.com/your_login_endpoint">
    </div>
    <div class="g_id_signin" data-type="standard"></div>
  </body>
</html>

В этом примере, предназначенном только для аутентификации, новая библиотека accounts.google.com/gsi/client , класс g_id_signin и объект g_id_onload заменяют ранее использовавшуюся библиотеку apis.google.com/js/platform.js и объект g-signin2 .

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

Хотя это не рекомендуется из-за увеличения сложностей при входе в систему, новую персонализированную кнопку можно отображать отдельно, без одновременного показа диалогового окна «Одно касание». Для этого установите атрибут data-auto_prompt в значение false .

API для HTML и JavaScript

В предыдущем примере показано, как использовать новый HTML API для добавления авторизации на ваш веб-сайт. В качестве альтернативы вы можете использовать функционально эквивалентный JavaScript API или комбинировать HTML и JavaScript API на своем сайте.

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

Вход с любой страницы одним касанием.

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

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

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

Ответ токена

Для входа пользователя в систему больше не требуется понимать или работать с кодами авторизации OAuth 2.0, токенами доступа или токенами обновления. Вместо этого для обмена информацией о статусе входа и профилем пользователя используется токен JSON Web Token (JWT). Для дальнейшего упрощения больше не требуется использовать методы доступа типа «геттер» для работы с данными профиля пользователя.

В ответ на запрос возвращается защищенный токен JWT, подписанный Google, либо:

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

В обоих случаях обновите существующие обработчики обратных вызовов, удалив:

• вызовы googleUser.getBasicProfile() ,
• ссылки на BasicProfile и связанные с ними вызовы методов getId() , getName() , getGivenName() , getFamilyName() , getImageUrl() , getEmail() и
• использование объекта AuthResponse .

Вместо этого используйте прямые ссылки на подполя credential в новом объекте JWT CredentialResponse для работы с данными профиля пользователя.

Кроме того, и только для режима перенаправления, обязательно предотвратите подделку межсайтовых запросов (CSRF) и проверьте токен Google ID на вашем бэкэнд-сервере .

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

Согласие пользователя и отзыв разрешения

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

Пользователи могут отозвать разрешения и отключить ваше приложение от своей учетной записи Google, перейдя по ссылке https://myaccount.google.com/permissions . В качестве альтернативы, они могут отключиться от вашего приложения напрямую, инициировав вызов API, который вы реализуете; прежний метод disconnect был заменен новым методом revoke .

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

Ранее для управления выходом пользователей из приложения использовался auth2.signOut() . Следует отказаться от использования auth2.signOut() и перевести приложение на управление состоянием сессии и статусом входа пользователя.

Состояние сессии и слушатели

Новая библиотека не сохраняет статус авторизации или состояние сессии для вашего веб-приложения.

Статус авторизации в учетной записи Google, а также состояние сессии и статус авторизации вашего приложения — это разные, отдельные понятия.

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

Если на вашем сайте включены функции «Вход через Google», «Вход в одно касание» или «Автоматический вход», пользователям сначала необходимо войти в свою учетную запись Google, чтобы:

• предоставить согласие на передачу профиля пользователя при первой регистрации или входе на ваш сайт.
• а позже — для авторизации при повторных посещениях вашего сайта.

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

Теперь вы отвечаете за непосредственное управление статусом авторизации пользователей вашего веб-приложения. Ранее функция Google Sign-In помогала отслеживать состояние сессии пользователя .

Удалите все ссылки на auth2.attachClickHandler() и зарегистрированные в нем обработчики обратного вызова.

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

Удалите все ссылки на listen() , auth2.currentUser и auth2.isSignedIn .

Печенье

Функция «Вход через Google» использует файлы cookie в ограниченном объеме; ниже приведено описание этих файлов cookie. Дополнительную информацию о других типах файлов cookie, используемых Google, см. в разделе «Как Google использует файлы cookie» .

Файл cookie G_ENABLED_IDPS , устанавливаемый предыдущей версией библиотеки Google Sign-in Platform Library, больше не используется.

Новая библиотека Google Identity Services может по желанию устанавливать эти междоменные файлы cookie в зависимости от параметров вашей конфигурации:

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

• g_csrf_token — это cookie-файл двойной отправки, используемый для предотвращения CSRF- атак, и устанавливается при вызове вашей конечной точки авторизации. Значение URI для входа в систему может быть задано явно или может по умолчанию соответствовать URI текущей страницы. Ваша конечная точка авторизации может быть вызвана при следующих условиях при использовании:

  • HTML API с data-ux_mode=redirect или при установке параметра data-login_uri , или

  • Использование JavaScript API с ux_mode=redirect и без вызова google.accounts.id.prompt() позволяет отображать вход в систему в одно касание или автоматический вход.

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

Если вы управляете несколькими доменами или поддоменами, см. раздел «Отображение одного касания для всех поддоменов» для получения дополнительных инструкций по работе с cookie-файлом g_state .

Справочник по миграции объектов для входа пользователя в систему