Библиотека JavaScript авторизации Google 3P для веб-сайтов – справочник по API

В этом справочнике описан API библиотеки JavaScript авторизации Google 3P, который можно использовать для загрузки кодов авторизации или токенов доступа от Google.

Метод: google.accounts.oauth2.initCodeClient

Метод initCodeClient инициализирует и возвращает клиентский код с конфигурациями в параметре.

google.accounts.oauth2.initCodeClient(config: CodeClientConfig)

Тип данных: Кодеклиентконфиг.

В следующей таблице перечислены свойства типа данных CodeClientConfig .

Характеристики
client_id Необходимый. Идентификатор клиента для вашего приложения. Это значение можно найти в консоли API.
scope Необходимый. Список областей, разделенных пробелами, которые определяют ресурсы, к которым ваше приложение может получить доступ от имени пользователя. Эти значения указывают на экран согласия, который Google отображает пользователю.
include_granted_scopes Необязательно, по умолчанию true . Позволяет приложениям использовать дополнительную авторизацию для запроса доступа к дополнительным областям в контексте. Если вы установите для этого параметра значение false и запрос на авторизацию будет предоставлен, то новый токен доступа будет охватывать только те области, для которых scope запрошена в этом CodeClientConfig .
redirect_uri Требуется для перенаправления UX. Определяет, куда сервер API перенаправляет пользователя после того, как пользователь завершает процесс авторизации. Значение должно точно совпадать с одним из разрешенных URI перенаправления для клиента OAuth 2.0, который вы настроили в консоли API, и должно соответствовать нашим правилам проверки URI перенаправления . Свойство будет игнорироваться всплывающим интерфейсом.
callback Требуется для всплывающего окна. Функция JavaScript, обрабатывающая возвращаемый ответ кода. Свойство будет игнорироваться UX перенаправления.
state Необязательный. Рекомендуется для перенаправления UX. Указывает любое строковое значение, которое ваше приложение использует для поддержания состояния между вашим запросом авторизации и ответом сервера авторизации.
enable_granular_consent Необязательно, по умолчанию true . Если установлено значение false , более детальные разрешения учетной записи Google будут отключены для идентификаторов клиентов OAuth, созданных до 2019 года. Если установлены оба параметра, enable_granular_consent и enable_serial_consent , вступит в силу только значение enable_granular_consent , а значение enable_serial_consent будет игнорироваться.

Никакого эффекта для новых идентификаторов клиентов OAuth, поскольку для них всегда включены более детальные разрешения.
enable_serial_consent Устарело, вместо этого следует использовать enable_granular_consent . Это имеет тот же эффект, что и enable_granular_consent . Существующие приложения, использующие enable_serial_consent могут продолжать это делать, но вам рекомендуется обновить свой код, чтобы использовать enable_granular_consent в следующем обновлении приложения.
login_hint Необязательный. Если ваше приложение знает, какой пользователь должен авторизовать запрос, оно может использовать это свойство, чтобы предоставить Google подсказку для входа. В случае успеха выбор учетной записи пропускается. Значение подполя адреса электронной почты или токена идентификатора для целевого пользователя. Для получения дополнительной информации см. поле login_hint в документации OpenID Connect.
hd Необязательный. Если вашему приложению известен домен Workspace, к которому принадлежит пользователь, используйте это, чтобы предоставить подсказку Google. В случае успеха учетные записи пользователей ограничиваются или предварительно выбираются для предоставленного домена. Для получения дополнительной информации см. поле hd в документации OpenID Connect.
ux_mode Необязательный. Режим UX, используемый для потока авторизации. По умолчанию поток согласия откроется во всплывающем окне. Допустимые значения: popup и redirect .
select_account Необязательно, по умолчанию установлено значение «false» . Логическое значение, предлагающее пользователю выбрать учетную запись.
error_callback Необязательный. Функция JavaScript, которая обрабатывает некоторые ошибки, не связанные с OAuth, например, не открывается всплывающее окно; или закрыт до того, как будет возвращен ответ OAuth.

Поле `type` входного параметра дает подробную причину.
  • popup_failed_to_open Не удалось открыть всплывающее окно.
  • popup_closed Всплывающее окно закрывается до возврата ответа OAuth.
  • неизвестный Заполнитель для других ошибок.

Тип данных: КодКлиент

Класс имеет только один общедоступный метод requestCode, который запускает поток пользовательского интерфейса кода OAuth 2.0.

interface CodeClient {
  requestCode(): void;
}

Тип данных: КодОтвет

Объект CodeResponse JavaScript будет передан вашему методу callback во всплывающем окне пользовательского интерфейса. В интерфейсе перенаправления CodeResponse будет передан в качестве параметров URL.

В следующей таблице перечислены свойства типа данных CodeResponse .

Характеристики
code Код авторизации успешного ответа токена.
scope Список областей, разделенных пробелами, одобренных пользователем.
state Строковое значение, которое ваше приложение использует для поддержания состояния между запросом авторизации и ответом.
error Одиночный код ошибки ASCII.
error_description Читаемый человеком текст ASCII, предоставляющий дополнительную информацию, которая помогает разработчику клиента понять возникшую ошибку.
error_uri URI, идентифицирующий удобочитаемую веб-страницу с информацией об ошибке, используемый для предоставления разработчику клиента дополнительной информации об ошибке.

Метод: google.accounts.oauth2.initTokenClient

Метод initTokenClient инициализирует и возвращает клиент токена с конфигурациями, указанными в параметре.

google.accounts.oauth2.initTokenClient(config: TokenClientConfig)

Тип данных: ТокенКлиентКонфиг.

В следующей таблице перечислены свойства типа данных TokenClientConfig .

Характеристики
client_id Необходимый. Идентификатор клиента для вашего приложения. Это значение можно найти в консоли API .
callback Необходимый. Функция JavaScript, обрабатывающая возвращаемый ответ токена.
scope Необходимый. Список областей, разделенных пробелами, которые определяют ресурсы, к которым ваше приложение может получить доступ от имени пользователя. Эти значения указывают на экран согласия, который Google отображает пользователю.
include_granted_scopes Необязательно, по умолчанию true . Позволяет приложениям использовать дополнительную авторизацию для запроса доступа к дополнительным областям в контексте. Если вы установите для этого параметра значение false и запрос на авторизацию будет предоставлен, то новый токен доступа будет охватывать только те области, для которых scope запрошена в этом TokenClientConfig .
prompt Необязательно, по умолчанию — select_account . Список подсказок, разделенных пробелами и чувствительных к регистру, которые должны быть представлены пользователю. Возможные значения:
  • пустая строка. Пользователь получит запрос только в первый раз, когда ваше приложение запросит доступ. Невозможно указать другие значения.
  • 'none' Не отображать экраны аутентификации или согласия. Не должно быть указано с другими значениями.
  • 'consent' Запросить у пользователя согласие.
  • 'select_account' Предложить пользователю выбрать учетную запись.
enable_granular_consent Необязательно, по умолчанию true . Если установлено значение false , более детальные разрешения учетной записи Google будут отключены для идентификаторов клиентов OAuth, созданных до 2019 года. Если установлены оба параметра, enable_granular_consent и enable_serial_consent , вступит в силу только значение enable_granular_consent , а значение enable_serial_consent будет игнорироваться.

Никакого эффекта для новых идентификаторов клиентов OAuth, поскольку для них всегда включены более детальные разрешения.
enable_serial_consent Устарело, вместо этого следует использовать enable_granular_consent . Это имеет тот же эффект, что и enable_granular_consent . Существующие приложения, использующие enable_serial_consent могут продолжать это делать, но вам рекомендуется обновить свой код, чтобы использовать enable_granular_consent в следующем обновлении приложения.
login_hint Необязательный. Если ваше приложение знает, какой пользователь должен авторизовать запрос, оно может использовать это свойство, чтобы предоставить Google подсказку для входа. В случае успеха выбор учетной записи пропускается. Значение подполя адреса электронной почты или токена идентификатора для целевого пользователя. Для получения дополнительной информации см. поле login_hint в документации OpenID Connect.
hd Необязательный. Если вашему приложению известен домен Workspace, к которому принадлежит пользователь, используйте это, чтобы предоставить подсказку Google. В случае успеха учетные записи пользователей ограничиваются или предварительно выбираются для предоставленного домена. Для получения дополнительной информации см. поле hd в документации OpenID Connect.
state Необязательный. Не рекомендуется. Указывает любое строковое значение, которое ваше приложение использует для поддержания состояния между вашим запросом авторизации и ответом сервера авторизации.
error_callback Необязательный. Функция JavaScript, которая обрабатывает некоторые ошибки, не связанные с OAuth, например, не открывается всплывающее окно; или закрыт до того, как будет возвращен ответ OAuth.

Поле `type` входного параметра дает подробную причину.
  • popup_failed_to_open Не удалось открыть всплывающее окно.
  • popup_closed Всплывающее окно закрывается до возврата ответа OAuth.
  • неизвестный Заполнитель для других ошибок.

Тип данных: ТокенКлиент

Класс имеет только один общедоступный метод requestAccessToken , который запускает поток пользовательского интерфейса токена OAuth 2.0.

interface TokenClient {
  requestAccessToken(overrideConfig?: OverridableTokenClientConfig): void;
}
Аргументы
overrideConfig Оверридаблетокенклиентконфиг Необязательный. Конфигурации, которые будут переопределены в этом методе.

Тип данных: Оверридаблетокенклиентконфиг.

В следующей таблице перечислены свойства типа данных OverridableTokenClientConfig .

Характеристики
scope Необязательный. Список областей, разделенных пробелами, которые определяют ресурсы, к которым ваше приложение может получить доступ от имени пользователя. Эти значения указывают на экран согласия, который Google отображает пользователю.
include_granted_scopes Необязательно, по умолчанию true . Позволяет приложениям использовать дополнительную авторизацию для запроса доступа к дополнительным областям в контексте. Если вы установите для этого параметра значение false и запрос на авторизацию будет предоставлен, то новый токен доступа будет охватывать только те области, для которых scope запрошена в этом OverridableTokenClientConfig .
prompt Необязательный. Разделенный пробелами и чувствительный к регистру список подсказок для пользователя.
enable_granular_consent Необязательно, по умолчанию true . Если установлено значение false , более детальные разрешения учетной записи Google будут отключены для идентификаторов клиентов OAuth, созданных до 2019 года. Если установлены оба параметра, enable_granular_consent и enable_serial_consent , вступит в силу только значение enable_granular_consent , а значение enable_serial_consent будет игнорироваться.

Никакого эффекта для новых идентификаторов клиентов OAuth, поскольку для них всегда включены более детальные разрешения.
enable_serial_consent Устарело, вместо этого следует использовать enable_granular_consent . Это имеет тот же эффект, что и enable_granular_consent . Существующие приложения, использующие enable_serial_consent могут продолжать это делать, но вам рекомендуется обновить свой код, чтобы использовать enable_granular_consent в следующем обновлении приложения.
login_hint Необязательный. Если ваше приложение знает, какой пользователь должен авторизовать запрос, оно может использовать это свойство, чтобы предоставить Google подсказку для входа. В случае успеха выбор учетной записи пропускается. Значение подполя адреса электронной почты или токена идентификатора для целевого пользователя. Для получения дополнительной информации см. поле login_hint в документации OpenID Connect.
state Необязательный. Не рекомендуется. Указывает любое строковое значение, которое ваше приложение использует для поддержания состояния между вашим запросом авторизации и ответом сервера авторизации.

Тип данных: TokenResponse

Объект JavaScript TokenResponse будет передан вашему методу обратного вызова во всплывающем окне пользовательского интерфейса.

В следующей таблице перечислены свойства типа данных TokenResponse .

Характеристики
access_token Токен доступа успешного ответа токена.
expires_in Время жизни токена доступа в секундах.
hd Размещенный домен, к которому принадлежит вошедший в систему пользователь.
prompt Значение подсказки, которое было использовано из возможного списка значений, заданных TokenClientConfig или OverridableTokenClientConfig.
token_type Тип выданного токена.
scope Список областей, разделенных пробелами, одобренных пользователем.
state Строковое значение, которое ваше приложение использует для поддержания состояния между запросом авторизации и ответом.
error Одиночный код ошибки ASCII.
error_description Удобочитаемый текст ASCII, предоставляющий дополнительную информацию, которая помогает разработчику клиента понять возникшую ошибку.
error_uri URI, идентифицирующий удобочитаемую веб-страницу с информацией об ошибке, используемый для предоставления разработчику клиента дополнительной информации об ошибке.

Метод: google.accounts.oauth2.hasGrantedAllScopes.

Проверяет, предоставил ли пользователю всю указанную область или области.

google.accounts.oauth2.hasGrantedAllScopes(
                                            tokenResponse: TokenResponse,
                                            firstScope: string, ...restScopes: string[]
                                          ): boolean;
Аргументы
tokenResponse TokenResponse Необходимый. Объект TokenResponse .
firstScope нить Необходимый. Область проверки.
restScopes нить[] Необязательный. Другие области для проверки.
Возврат
логическое значение Истинно, если предоставлены все области.

Метод: google.accounts.oauth2.hasGrantedAnyScope.

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

google.accounts.oauth2.hasGrantedAnyScope(
                                           tokenResponse: TokenResponse,
                                           firstScope: string, ...restScopes: string[]
                                         ): boolean;
Аргументы
tokenResponse TokenResponse Необходимый. Объект TokenResponse .
firstScope нить Необходимый. Область проверки.
restScopes нить[] Необязательный. Другие области для проверки.
Возврат
логическое значение Истинно, если какая-либо из областей предоставлена.

Метод: google.accounts.oauth2.revoke

Метод revoke отзывает все области, предоставленные пользователем приложению. Для отзыва разрешения необходим действительный токен доступа.

google.accounts.oauth2.revoke(accessToken: string, done: () => void): void;
Аргументы
accessToken нить Необходимый. Действительный токен доступа.
callback функция Необязательный. Обработчик ответа на отзыв .

Тип данных: отзывответ

В ваш метод обратного вызова будет передан объект JavaScript RevocationResponse .

В следующей таблице перечислены свойства типа данных RevocationResponse .

Характеристики
successful Логическое значение. true в случае успеха, false в случае неудачи.
error Нить. Неопределенный успех. Одиночный код ошибки ASCII. Сюда входят, помимо прочего , стандартные коды ошибок OAuth 2.0 . Распространенные ошибки метода revoke :
  • invalid_token — срок действия токена уже истек или он был отозван до вызова метода revoke . В большинстве случаев вы можете считать, что грант, связанный с accessToken , отозван.
  • invalid_request — Токен не подлежит отзыву. Вы должны убедиться, что accessToken является действительным учетным данными Google OAuth 2.0.
error_description Нить. Неопределенный успех. Читаемый человеком текст ASCII предоставляет дополнительную информацию о свойстве error . Разработчики могут использовать это, чтобы лучше понять возникшую ошибку. Строка error_description представлена ​​только на английском языке. Для распространенных ошибок, перечисленных в error соответствующее error_description :
  • invalid_token — срок действия токена истек или он отозван.
  • invalid_request — Токен не подлежит отзыву.