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

В этом руководстве обсуждается внедрение 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 .
  • Обязательное принятие (дата будет определена) 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 .

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

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

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

Найдите запрос библиотеки входа в 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. Если это так:

Повторите этот процесс для каждого 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 добавляет модальное диалоговое окно, отображаемое браузером, и обновляет требования к активации пользователя.

Image of FedCM modal dialog

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    Инициализация библиотеки выполняется при загрузке документа с помощью функции запуска, которая gapi.auth2.init gapi.load 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.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 .