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

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

Если ваш клиент использует для авторизации клиентскую библиотеку Google API для JavaScript или другие более ранние библиотеки, дополнительную информацию см. в разделе «Миграция на службы идентификации Google» .

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

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

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

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

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

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

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

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

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

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

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

Пример миграции входа в систему

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

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

Предыдущая библиотека платформы входа в Google: 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 gapi.client

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

• ваши тестовые и рабочие приложения используют отдельные проекты и имеют свои собственные идентификаторы клиентов,
• Тип идентификатора клиента 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 Журнал использования устаревших возможностей в консоли JS. Также войдите в хранилище сеанса, если установлено необязательное имя ключа: 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 .

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

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

API HTML и JavaScript

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

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

Вход в систему с любой страницы одним нажатием

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

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

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

Ответ токена

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

Защищенные учетные данные токена JWT ID, подписанные Google, возвращаются либо:

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

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

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

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

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

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

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

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

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

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

Раньше auth2.signOut() можно было использовать для управления выходом пользователей из вашего приложения. Любое использование auth2.signOut() должно быть удалено, и ваше приложение должно напрямую управлять состоянием сеанса пользователя и статусом входа.

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

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

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

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

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

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

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

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

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

Раньше прослушиватели использовались для обмена изменениями в статусе входа в учетную запись Google пользователя. Слушатели больше не поддерживаются.

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

Файлы cookie

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

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

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

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

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

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

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

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

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

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