Войти с помощью ссылки Google HTML API

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

Элемент с идентификатором "g_id_onload"

Атрибуты данных «Войти через Google» можно добавлять в любые видимые или невидимые элементы, такие как <div> и <span> . Единственное требование — идентификатор элемента должен быть установлен на g_id_onload . Не следует добавлять этот идентификатор к нескольким элементам одновременно.

Атрибуты данных

В следующей таблице перечислены атрибуты данных с их описаниями:

Типы атрибутов

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

data-client_id

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

цветовая схема данных

В этом поле задается цветовая схема, применяемая к подсказке «Одно касание». Дополнительную информацию см. в следующей таблице:

В таблице ниже перечислены доступные цветовые схемы и их описания.

data-auto_prompt

Этот атрибут определяет, отображать ли функцию «Одно касание» или нет. Значение по умолчанию — true . Если это значение равно false , функция «Одно касание» в Google не отображается. Дополнительную информацию см. в следующей таблице:

data-auto_select

Этот атрибут определяет, следует ли автоматически возвращать токен ID без какого-либо взаимодействия с пользователем, если ваше приложение было одобрено только одной сессией Google. Значение по умолчанию — false . Дополнительную информацию см. в следующей таблице:

data-login_uri

Этот атрибут представляет собой URI вашей конечной точки входа.

Значение должно точно совпадать с одним из разрешенных URI перенаправления для клиента OAuth 2.0, который вы настроили на платформе Google Auth, и должно соответствовать нашим правилам проверки URI перенаправления .

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

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

Ваша точка входа в систему должна обрабатывать POST-запросы, содержащие параметр credential со значением токена идентификатора в теле запроса.

Дополнительную информацию см. в следующей таблице:

обратный вызов данных

Этот атрибут содержит имя функции JavaScript, которая обрабатывает возвращаемый токен ID. Дополнительную информацию см. в следующей таблице:

Может быть использован один из атрибутов data-login_uri или data-callback . Это зависит от следующих конфигураций компонента и режима UX:

• Атрибут data-login_uri необходим для режима redirect кнопки "Войти через Google", в котором игнорируется атрибут data-callback .

• Для режима popup окна Google One Tap и режима пользовательского интерфейса кнопки входа в Google необходимо установить один из этих двух атрибутов. Если установлены оба, атрибут data-callback имеет более высокий приоритет.

Функции JavaScript, находящиеся внутри пространства имен, не поддерживаются HTML API. Вместо этого используйте глобальную функцию JavaScript без пространства имен. Например, используйте mylibCallback вместо mylib.callback .

data-native_login_uri

Этот атрибут представляет собой URL-адрес конечной точки обработчика учетных данных пароля. Если вы установите атрибут data-native_login_uri или data-native_callback , библиотека JavaScript будет использовать встроенный менеджер учетных данных, если сессия Google отсутствует. Вы не можете установить одновременно атрибуты data-native_callback и data-native_login_uri . Дополнительную информацию см. в следующей таблице:

data-native_callback

Этот атрибут указывает имя функции JavaScript, которая обрабатывает учетные данные пароля, возвращаемые встроенным менеджером учетных данных браузера. Если вы установите атрибут data-native_login_uri или data-native_callback , библиотека JavaScript будет использовать встроенный менеджер учетных данных, если сессия Google отсутствует. Нельзя устанавливать одновременно data-native_callback и data-native_login_uri . Дополнительную информацию см. в следующей таблице:

Функции JavaScript, находящиеся внутри пространства имен, не поддерживаются HTML API. Вместо этого используйте глобальную функцию JavaScript без пространства имен. Например, используйте mylibCallback вместо mylib.callback .

data-native_id_param

При отправке учетных данных пароля в конечную точку обработчика учетных данных пароля вы можете указать имя параметра для поля credential.id . Имя по умолчанию — email . Дополнительную информацию см. в следующей таблице:

data-native_password_param

При отправке учетных данных пароля в конечную точку обработчика учетных данных пароля вы можете указать имя параметра для значения credential.password . Имя по умолчанию — password . Дополнительную информацию см. в следующей таблице:

data-cancel_on_tap_outside

Этот атрибут определяет, следует ли отменять запрос One Tap, если пользователь щелкает вне поля ввода. Значение по умолчанию — true . Чтобы отключить эту функцию, установите значение false . Дополнительную информацию см. в следующей таблице:

data-prompt_parent_id

Этот атрибут задаёт DOM-идентификатор элемента-контейнера. Если он не задан, в правом верхнем углу окна отображается подсказка «Одно касание». Дополнительную информацию см. в следующей таблице:

data-skip_prompt_cookie

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

дата-нонс

Этот атрибут представляет собой случайную строку, используемую токеном ID для предотвращения атак повторного воспроизведения. Дополнительную информацию см. в следующей таблице:

Длина одноразового числа (nonce) ограничена максимальным размером JWT, поддерживаемым вашей средой, а также индивидуальными ограничениями размера HTTP-запросов для каждого браузера и сервера.

контекст данных

Это поле изменяет текст заголовка и сообщений, отображаемых в подсказке One Tap; для браузеров ITP эффект отсутствует. По умолчанию используется signin .

Дополнительную информацию см. в следующей таблице:

В таблице ниже перечислены все доступные контексты и их описания:

data-moment_callback

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

Дополнительную информацию см. в следующей таблице:

Функции JavaScript, находящиеся внутри пространства имен, не поддерживаются HTML API. Вместо этого используйте глобальную функцию JavaScript без пространства имен. Например, используйте mylibCallback вместо mylib.callback .

data-state_cookie_domain

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

data-ux_mode

Этот атрибут задает сценарий взаимодействия пользователя с кнопкой «Войти через Google». Значение по умолчанию — popup . Этот атрибут не влияет на взаимодействие пользователя в одно касание. Дополнительную информацию см. в следующей таблице:

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

data-allowed_parent_origin

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

В таблице ниже перечислены поддерживаемые типы значений и их описания.

Если значение атрибута data-allowed_parent_origin недопустимо, инициализация промежуточного режима iframe в режиме One Tap завершится неудачей и остановится.

Также поддерживаются префиксы с подстановочными знаками. Например, "https://*.example.com" соответствует example.com и его поддоменам на всех уровнях (например, news.example.com , login.news.example.com ). Что следует учитывать при использовании подстановочных знаков:

• Строки шаблонов не могут состоять только из подстановочного знака и домена верхнего уровня. Например https:// .com и https:// .co.uk недопустимы, поскольку "https:// .example.com" соответствует example.com и всем его поддоменам. Используйте список, разделенный запятыми, для представления двух разных доменов. Например, "https://example1.com,https:// .example2.com" соответствует доменам example1.com , example2.com и поддоменам example2.com
• Домены с подстановочными знаками должны начинаться с защищенной схемы https://, поэтому "*.example.com" считается недействительным.

data-intermediate_iframe_close_callback

Этот параметр переопределяет стандартное поведение промежуточного iframe, которое происходит при ручном закрытии One Tap нажатием кнопки «X» в пользовательском интерфейсе One Tap. По умолчанию промежуточный iframe немедленно удаляется из DOM.

Поле data-intermediate_iframe_close_callback действует только в режиме промежуточного iframe. И оно влияет только на промежуточный iframe, а не на iframe с одним касанием. Интерфейс One Tap удаляется перед вызовом функции обратного вызова.

Функции JavaScript, находящиеся внутри пространства имен, не поддерживаются HTML API. Вместо этого используйте глобальную функцию JavaScript без пространства имен. Например, используйте mylibCallback вместо mylib.callback .

data-itp_support

В этом поле определяется, следует ли включать улучшенный пользовательский интерфейс One Tap в браузерах, поддерживающих интеллектуальную защиту от отслеживания (ITP). Значение по умолчанию — false . Дополнительную информацию см. в следующей таблице:

data-login_hint

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

Для получения более подробной информации см. документацию OpenID Connect по параметру login_hint .

данные-HD

Если у пользователя несколько учетных записей и ему необходимо входить в систему только с помощью учетной записи Workspace, используйте эту опцию для указания доменного имени для Google. В случае успеха, при выборе учетной записи будут отображаться только учетные записи пользователей, относящиеся к указанному домену. Использование подстановочного знака: * позволяет пользователю выбирать только учетные записи Workspace и исключает учетные записи обычных пользователей (user@gmail.com) при выборе учетной записи.

Для получения более подробной информации см. документацию OpenID Connect для hd .

data-use_fedcm_for_prompt

Разрешите браузеру управлять запросами на авторизацию пользователей и выступать посредником в процессе входа в систему между вашим веб-сайтом и Google. По умолчанию — false. Дополнительную информацию см. на странице «Переход на FedCM» .

data-use_fedcm_for_button

Это поле определяет, следует ли использовать пользовательский интерфейс кнопок FedCM в Chrome (настольная версия M125+ и Android M128+). По умолчанию — false . Дополнительную информацию см. в следующей таблице:

data-button_auto_select

Это поле определяет, следует ли включить опцию автоматического выбора для процесса нажатия кнопки FedCM. Если она включена, пользователи с активной сессией Google будут автоматически авторизованы, минуя запрос выбора учетной записи. По умолчанию — false . Необходимо явно включить автоматический вход с помощью кнопки во время запуска функции. Дополнительную информацию см. в следующей таблице:

Элемент с классом "g_id_signin"

Если добавить атрибут g_id_signin к атрибуту ` class элемента, элемент отобразится как кнопка «Войти через Google».

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

Атрибуты визуальных данных

В следующей таблице перечислены атрибуты визуальных данных и их описания:

Типы атрибутов

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

тип данных

Тип кнопки. Значение по умолчанию — standard . Дополнительную информацию см. в следующей таблице:

В таблице ниже перечислены все доступные типы кнопок и их описания:

Тип
standard
icon

тема данных

Тема оформления кнопок. Значение по умолчанию — outline . Дополнительную информацию см. в следующей таблице:

В таблице ниже перечислены доступные темы оформления и их описания:

Тема
outline
filled_blue
filled_black

размер данных

Размер кнопки. Значение по умолчанию — large . Дополнительную информацию см. в следующей таблице:

В таблице ниже перечислены доступные размеры кнопок и их описания.

Размер
large
medium
small

данные-текст

Текст кнопки. Значение по умолчанию — signin_with . Визуальных различий в тексте кнопок-иконок с разными атрибутами data-text нет. Единственное исключение — когда текст читается для обеспечения доступности экрана.

Дополнительную информацию см. в следующей таблице:

В таблице ниже перечислены доступные тексты для кнопок и их описания:

Текст
signin_with
signup_with
continue_with
signin

форма данных

Форма кнопки. Значение по умолчанию — rectangular . Дополнительную информацию см. в следующей таблице:

В таблице ниже перечислены доступные формы кнопок и их описания:

Форма
rectangular
pill
circle
square

data-logo_alignment

Выравнивание логотипа Google. Значение по умолчанию — left . Этот атрибут применяется только к standard типу кнопок. Дополнительную информацию см. в следующей таблице:

В таблице ниже перечислены доступные варианты выравнивания и их описания:

выравнивание логотипа
left
center

ширина данных

Минимальная ширина кнопки в пикселях. Максимальная доступная ширина — 400 пикселей.

Дополнительную информацию см. в следующей таблице:

локаль данных

Необязательно. Отображайте текст кнопки с использованием указанной локали, в противном случае используйте локаль из учетной записи Google пользователя или настроек браузера. Добавьте параметр hl и код языка в директиву src при загрузке библиотеки, например: gsi/client?hl=<iso-639-code> .

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

Дополнительную информацию см. в следующей таблице:

data-click_listener

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

  <script>
    function onClickHandler(){
      console.log("Sign in with Google button clicked...")
    }
  </script>
  .....
  <div class="g_id_signin"
      data-size="large"
      data-theme="outline"
      data-click_listener="onClickHandler">
  </div>

В этом примере при нажатии кнопки «Войти через Google» в консоль выводится сообщение «Кнопка „Войти через Google“ нажата...» .

состояние данных

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

Дополнительную информацию см. в следующей таблице:

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

Ваши серверные конечные точки должны обрабатывать следующие HTTP POST запросы.

Конечная точка обработчика токенов идентификации

Конечная точка обработчика ID-токена обрабатывает ID-токен. В зависимости от статуса соответствующей учетной записи вы можете выполнить вход пользователя и либо перенаправить его на страницу регистрации, либо на страницу привязки учетной записи для получения дополнительной информации. Клиенты ДОЛЖНЫ игнорировать нераспознанные параметры ответа.

Пример запроса к вашей конечной точке авторизации:

POST /login HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Cookie: g_csrf_token=<RANDOM_STRING>
Host: www.example.com

credential=<JWT_ENCODED_ID_TOKEN>&g_csrf_token=<RANDOM_STRING>

HTTP POST запрос содержит следующую информацию:

учетные данные

После декодирования токен ID будет выглядеть следующим образом:

header
{
  "alg": "RS256",
  "kid": "f05415b13acb9590f70df862765c655f5a7a019e", // JWT signature
  "typ": "JWT"
}
payload
{
  "iss": "https://accounts.google.com", // The JWT's issuer
  "nbf":  161803398874,
  "aud": "314159265-pi.apps.googleusercontent.com", // Your server's client ID
  "sub": "3141592653589793238", // The unique ID of the user's Google Account
  "hd": "gmail.com", // If present, the host domain of the user's GSuite email address
  "email": "elisa.g.beckett@gmail.com", // The user's email address
  "email_verified": true, // true, if Google has verified the email address
  "azp": "314159265-pi.apps.googleusercontent.com",
  "name": "Elisa Beckett",
                            // If present, a URL to user's profile picture
  "picture": "https://lh3.googleusercontent.com/a-/e2718281828459045235360uler",
  "given_name": "Eliza",
  "family_name": "Beckett",
  "iat": 1596474000, // Unix timestamp of the assertion's creation time
  "exp": 1596477600, // Unix timestamp of the assertion's expiration time
  "jti": "abc161803398874def"
}

Клиенты ОБЯЗАНЫ игнорировать непризнанные претензии по JWT.

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

Используя поля email , email_verified и hd вы можете определить, является ли адрес электронной почты хостинг-провайдером Google и авторитетным источником информации для этого адреса. В случаях, когда авторитетным источником является Google, подтверждается, что пользователь является законным владельцем учетной записи.

Примеры случаев, когда Google является авторитетным источником информации:

• email присутствует суффикс @gmail.com , это учетная запись Gmail.
• email_verified имеет значение true, а hd установлен, это учетная запись Google Workspace.

Пользователи могут зарегистрировать учетные записи Google без использования Gmail или Google Workspace. Если email не содержит суффикса @gmail.com и отсутствует hd , Google не является авторитетным источником, и для подтверждения пользователя рекомендуется использовать пароль или другие методы проверки подлинности. email_verified также может быть истинным, поскольку Google первоначально подтвердил пользователя при создании учетной записи Google, однако право собственности на сторонний почтовый аккаунт могло с тех пор измениться.

Поле exp показывает время истечения срока действия токена на стороне вашего сервера . Для токена ID, полученного при входе через Google, это один час. Вам необходимо подтвердить токен до истечения срока действия. Не используйте exp для управления сессиями. Истекший токен ID не означает, что пользователь вышел из системы. За управление сессиями пользователей отвечает ваше приложение.

g_csrf_token

Токен защиты от подделки запросов. Это токен защиты от межсайтовой подделки запросов (CSRF), созданный библиотекой gsi/client . Случайное значение включается как в качестве Cookie, так и в качестве параметра запроса в теле POST-запроса. Если эти два значения не совпадают при обработке запроса на вашем сервере, запрос следует считать недействительным.

select_by

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

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

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

• Перед тем как передать учетные данные токена идентификации вашему приложению, пользователь либо

  • нажали кнопку «Подтвердить», чтобы дать согласие на передачу учетных данных, или
  • ранее дал согласие и использовал функцию «Выбрать учетную запись», чтобы выбрать учетную запись Google.

Значение этого поля устанавливается на один из следующих типов:

состояние

Этот параметр определяется только тогда, когда пользователь нажимает кнопку «Войти через Google» для авторизации, и указан атрибут data-state нажатой кнопки. Значение этого поля совпадает со значением, указанным в атрибуте data-state кнопки.

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

конечная точка обработчика учетных данных пароля

Конечная точка обработчика учетных данных паролей обрабатывает учетные данные паролей, полученные встроенным менеджером учетных данных.

HTTP POST запрос содержит следующую информацию: