Вход в Google с помощью API FedCM

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

Поддержка библиотеки Google Sign-In устарела. Дополнительные сведения см. в руководстве по прекращению поддержки и прекращению поддержки .

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

Статус библиотеки

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

Обновление с обратной совместимостью добавляет API-интерфейсы FedCM в библиотеку входа в Google. Хотя большинство изменений происходят плавно, обновление вносит изменения в пользовательские запросы , политику разрешений iframe и политику безопасности контента (CSP). Эти изменения могут повлиять на ваше веб-приложение и потребовать внесения изменений в код приложения и конфигурацию сайта.

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

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

Хронология

Последнее обновление: сентябрь 2024 г.

Ниже приведены даты и изменения, влияющие на поведение пользователя при входе в систему:

• Март 2023 г. Прекращение поддержки библиотеки платформы входа в Google.
• Июль 2024 г. Начинается переходный период , и добавляется поддержка библиотеки платформы входа Google для API FedCM. По умолчанию Google контролирует процент запросов на вход пользователей с помощью FedCM в это время. Веб-приложения могут явно переопределить это поведение с помощью параметра use_fedcm .
• Март 2025 г. Обязательное принятие API-интерфейсов FedCM библиотекой платформы входа Google, после чего параметр use_fedcm игнорируется, и все запросы на вход пользователей используют FedCM.

Следующие шаги

Есть три варианта, которым вы можете следовать:

1. Проведите оценку воздействия и при необходимости обновите свое веб-приложение. Этот подход оценивает, используются ли функции, требующие изменений в вашем веб-приложении. Инструкции приведены в следующем разделе данного руководства.
2. Перейдите в библиотеку Google Identity Services (GIS). Настоятельно рекомендуется перейти на последнюю и поддерживаемую библиотеку входа. Сделайте это, следуя этим инструкциям .
3. Ничего не делайте. Ваше веб-приложение будет автоматически обновлено, когда библиотека входа Google перейдет на API FedCM для входа пользователей. Это наименьшая работа, но существует некоторый риск того, что пользователи не смогут войти в ваше веб-приложение.

Проведите оценку воздействия

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

Настраивать

API браузера и последняя версия библиотеки платформы входа Google необходимы для использования FedCM во время входа пользователя.

Прежде чем идти дальше:

• Обновите Chrome для ПК до последней версии. Chrome для Android требует версии M128 или более поздней, и его нельзя протестировать с использованием более ранних версий.

• Откройте chrome://flags и установите эти значения для следующих функций:

  • #fedcm-authz включено
  • #tracking-protection-3pcd Включено
  • # Third-party-cookie-deprecation-trial отключено
  • #tpcd-metadata-grants отключено
  • #tpcd-heuristics-grants отключено

  и перезапустите Chrome.

• Установите для use_fedcm значение true при инициализации библиотеки платформы входа в Google в вашем веб-приложении. Обычно инициализация выглядит так:

  • gapi.client.init({use_fedcm: true}) или
  • gapi.auth2.init({use_fedcm: true}) или
  • gapi.auth2.authorize({use_fedcm: true}) .

• Недействительные кэшированные версии библиотеки платформы входа в Google. Обычно этот шаг не нужен, поскольку последняя версия библиотеки загружается напрямую в браузер путем включения api.js , client.js или platform.js в тег <script src> (запрос может использовать любое из этих имен пакетов для библиотека).

• Подтвердите настройки OAuth для вашего идентификатора клиента OAuth:

  1. Откройте страницу «Учетные данные» Google API Console

  2. Убедитесь, что URI вашего веб-сайта включен в авторизованные источники JavaScript . URI включает только схему и полное имя хоста. Например, https://www.example.com .

     Ключевой момент: для локального тестирования или разработки добавьте http://localhost и http://localhost:<port_number> .

  3. При желании учетные данные могут быть возвращены с помощью перенаправления на конечную точку, которую вы размещаете, а не через обратный вызов JavaScript. В этом случае убедитесь, что ваши URI перенаправления включены в список «Разрешенные URI перенаправления» . URI перенаправления включают схему, полное имя хоста и путь и должны соответствовать правилам проверки URI перенаправления . Например, https://www.example.com/auth-receiver .

     Ключевой момент: при тестировании с использованием http и localhost установите для заголовка Referrer-Policy в веб-приложении значение Referrer-Policy: no-referrer-when-downgrade .

Тестирование

После выполнения инструкций в настройке:

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

• Следуйте инструкциям в этих разделах данного руководства, чтобы выявить и устранить известные проблемы:

  • Найдите запрос библиотеки входа в Google.
  • Проверьте политику разрешений iframe
  • Проверьте политику безопасности контента
  • Проверьте изменения подсказок пользователя

• Найдите в консоли любые ошибки или предупреждения, связанные с библиотекой входа в Google.

• Повторяйте этот процесс до тех пор, пока не исчезнут ошибки и вы не сможете успешно войти в систему. Вы можете подтвердить успешный вход, подтвердив, что BasicProfile.getEmail() возвращает ваш адрес электронной почты и что GoogleUser.isSignedIn() имеет True .

Найдите запрос библиотеки входа в Google.

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

• В Chrome откройте панель DevTools Network и перезагрузите страницу.
• Используйте значения в столбцах «Домен» и «Имя» , чтобы найти запрос библиотеки:
  • Домен — apis.google.com и
  • Имя — api.js , client.js или platform.js . Конкретное значение имени зависит от пакета библиотеки, запрошенного документом.

Например, отфильтруйте apis.google.com в столбце «Домен» и platform.js в столбце «Имя» .

Проверьте политику разрешений iframe

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

Выполнив инструкции по запросу «Найти библиотеку входа в Google» , выберите запрос библиотеки входа в Google на панели «Сеть DevTools» и найдите заголовок Sec-Fetch-Site в разделе «Заголовки запроса» на вкладке «Заголовки» . Если значение заголовка:

• same-site или same-origin , тогда политики перекрестного происхождения не применяются, и никаких изменений не требуется.
• изменения cross-origin могут потребоваться, если используется iframe.

Чтобы подтвердить наличие iframe:

• Выберите панель «Элементы» в Chrome DevTools и
• Используйте Ctrl-F, чтобы найти iframe в документе.

Если обнаружен iframe, проверьте документ на наличие вызовов функцийgapi.auth2 или директив script src , которые загружают библиотеку входа в Google в iframe. Если это так:

• Добавьте политику allow="identity-credentials-get" в родительский iframe.

Повторите этот процесс для каждого iframe в документе. iframes могут быть вложенными, поэтому обязательно добавьте директивуallow ко всем окружающим родительским iframe.

Проверьте политику безопасности контента

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

Выполнив инструкции по запросу «Найти библиотеку входа в Google» , выберите запрос библиотеки входа в Google на панели «Сеть» DevTools и найдите заголовок Content-Security-Policy в разделе «Заголовки ответов» на вкладке «Заголовки» .

Если заголовок не найден, никаких изменений не требуется. В противном случае проверьте, определены ли какие-либо из этих директив CSP в заголовке CSP, и обновите их:

• Добавление https://apis.google.com/js/ , https://accounts.google.com/gsi/ и https://acounts.google.com/o/fedcm/ в любой connect-src , default-src или директивы frame-src .

• Добавление https://apis.google.com/js/bundle-name.js в директиву script-src . Замените bundle-name.js на api.js , client.js или platform.js в зависимости от того, какой пакет библиотеки запрашивает документ.

Проверьте изменения подсказок пользователя

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

Ключевой момент: согласие предоставляется для каждого экземпляра браузера, поэтому для использования Chrome на другом устройстве также требуется однократное согласие, независимо от того, делали ли пользователи это ранее на другом устройстве.

Модальный диалог

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

Примечание. Размер и положение модального диалогового окна недоступны в среде выполнения JavaScript.

Активация пользователя

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

• пользователь сначала входит в веб-приложение, используя новый экземпляр браузера, или
• Вызывается GoogleAuth.signIn .

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

Если вы выберете FedCM и вызовете GoogleAuth.signIn , то в следующий раз, когда тот же пользователь посетит ваш веб-сайт, gapi.auth2.init сможет получить информацию для входа пользователя во время инициализации без взаимодействия с пользователем.

Ключевой момент: при первом вызове GoogleAuth.signIn требуется жест пользователя и запрос на согласие, даже если это происходит в событии onload документа.

Распространенные случаи использования

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

• Интеграция входа в Google в ваше веб-приложение

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

  Инициализация библиотеки выполняется классом g-signin2 gapi.load который вызываетgapi.load gapi.auth2.init .

  Жест пользователя, событие onclick элемента <div> , вызывает auth2.signIn во время входа или auth2.signOut при выходе.

• Создание пользовательской кнопки входа в Google

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

  Инициализация библиотеки выполняется через событие onload библиотеки platform.js , а кнопка отображается с помощью gapi.signin2.render .

  Жест пользователя, нажимающий кнопку входа, вызывает auth2.signIn .

  Во второй демонстрации элемент <div> , стили CSS и пользовательское изображение используются для управления внешним видом кнопки входа. Для входа в систему и установления нового сеанса требуется взаимодействие с пользователем.

  Инициализация библиотеки выполняется при загрузке документа с помощью функции запуска gapi.load которая вызываетgapi.load, gapi.auth2.init gapi.auth2.attachClickHandler .

  Жест пользователя, событие onclick элемента <div> , вызывает auth2.signIn с использованием auth2.attachClickHandler во время входа или auth2.signOut при выходе.

• Мониторинг состояния сеанса пользователя

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

  Инициализация библиотеки выполняется путем прямого gapi.load , gapi.auth2.init gapi.auth2.attachClickHandler() после загрузки platform.js с помощью script src .

  Жест пользователя, событие onclick элемента <div> , вызывает auth2.signIn с использованием auth2.attachClickHandler во время входа или auth2.signOut при выходе.

• Запрос дополнительных разрешений

  В этой демонстрации нажатие кнопки используется для запроса дополнительных областей OAuth 2.0, получения нового токена доступа, а для уже вошедших в систему пользователей событие onload страницы возвращает учетные данные пользователя. Для входа в систему и установления нового сеанса требуется взаимодействие с пользователем.

  Инициализация библиотеки выполняется событием onload для библиотеки platform.js посредством gapi.signin2.render .

  Жест пользователя, нажав на элемент <button> , запускает запрос дополнительных областей OAuth 2.0 с использованием googleUser.grant или auth2.signOut при выходе.

• Интеграция входа в Google с использованием прослушивателей

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

  Инициализация библиотеки выполняется при загрузке документа с помощью функции запуска gapi.load которая вызываетgapi.load, gapi.auth2.init gapi.auth2.attachClickHandler . Затем auth2.isSignedIn.listen и auth2.currentUser.listen используются для настройки уведомления об изменениях состояния сеанса. Наконец, auth2.SignIn вызывается для возврата учетных данных для вошедших в систему пользователей.

  Жест пользователя, событие onclick элемента <div> , вызывает auth2.signIn с использованием auth2.attachClickHandler во время входа или auth2.signOut при выходе.

• Вход в Google для серверных приложений

  В этой демонстрации жест пользователя используется для запроса кода аутентификации OAuth 2.0, а обратный вызов JS выполняет вызов AJAX для отправки ответа на внутренний сервер для проверки.

  Инициализация библиотеки выполняется с помощью события onload для библиотеки platform.js , которая использует функцию запуска для gapi.load gapi.auth2.init .

  Жест пользователя, щелкающий элемент <button> , запускает запрос кода авторизации путем вызова auth2.grantOfflineAccess .

• Межплатформенный единый вход

  FedCM требует согласия для каждого экземпляра браузера, даже если пользователи Android уже вошли в систему, необходимо единоразовое согласие.

Управляйте переходным периодом

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

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

Подписаться

Может быть полезно контролировать, используют ли все или некоторые попытки входа на ваш сайт API-интерфейсы FedCM. Для этого установите для use_fedcm значение true при инициализации библиотеки платформы. В этом случае запрос на вход пользователя использует API FedCM.

Уклоняться

В течение переходного периода определенный процент попыток входа пользователей на ваш сайт будет по умолчанию использовать API FedCM. Если для внесения изменений в ваше приложение требуется больше времени, вы можете временно отказаться от использования API FedCM. Для этого при инициализации библиотеки платформы установите для use_fedcm значение false . В этом случае запрос на вход пользователя не будет использовать API FedCM.

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

Получить помощь

Ищите или задавайте вопросы на StackOverflow, используя тег google-signin .