Библиотека 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 — Токен не подлежит отзыву.