browser.identity

Описание

Используйте chrome.identity API, чтобы получить токены доступа OAuth2.

Разрешения

identity

Типы

AccountInfo

Свойства

  • id

    string

    Уникальный идентификатор аккаунта. Этот идентификатор не меняется в течение всего времени существования аккаунта.

AccountStatus

Chrome 84+ browser.* начиная с Chrome 148

Перечисление

"SYNC"
Указывает, что синхронизация включена для основного аккаунта.

ANY
Указывает на наличие основного аккаунта, если он есть.

GetAuthTokenResult

Chrome 105+ browser.* начиная с Chrome 148

Свойства

  • grantedScopes

    string[] необязательно

    Список областей действия OAuth2, предоставленных расширению.

  • токен

    Строка (необязательно)

    Токен, связанный с запросом.

InvalidTokenDetails

Свойства

  • токен

    string

    Токен, который нужно удалить из кеша.

ProfileDetails

Chrome 84+ browser.* начиная с Chrome 148

Свойства

  • accountStatus

    AccountStatus необязательный

    Статус основного аккаунта, вошедшего в профиль, для которого нужно вернуть ProfileUserInfo. По умолчанию используется статус аккаунта SYNC.

ProfileUserInfo

Свойства

  • email

    string

    Адрес электронной почты аккаунта пользователя, который вошел в текущий профиль. Если пользователь не вошел в аккаунт или не указано разрешение манифеста identity.email, поле остается пустым.

  • id

    string

    Уникальный идентификатор аккаунта. Этот идентификатор не меняется в течение всего времени существования аккаунта. Если пользователь не вошел в аккаунт или (в версии 41 и более поздних) не указано разрешение манифеста identity.email, поле остается пустым.

TokenDetails

Свойства

  • аккаунт

    AccountInfo необязательный

    Идентификатор аккаунта, токен которого нужно вернуть. Если аккаунт не указан, функция будет использовать аккаунт из профиля Chrome: аккаунт синхронизации, если он есть, или первый веб-аккаунт Google.

  • enableGranularPermissions

    Логическое значение (необязательно)

    Chrome 87 и более поздних версий browser.* начиная с Chrome 148

    Флаг enableGranularPermissions позволяет расширениям заранее включить окно запроса доступа с детализированными разрешениями, в котором запрашиваемые разрешения предоставляются или отклоняются по отдельности.

  • интерактивный

    Логическое значение (необязательно)

    Для получения токена пользователю может потребоваться войти в Chrome или одобрить запрошенные приложением области действия. Если флаг interactive имеет значение true, getAuthToken будет запрашивать у пользователя подтверждение, когда это необходимо. Если для флага задано значение false или он не указан, getAuthToken будет возвращать ошибку каждый раз, когда требуется запрос.

  • диапазоны

    string[] необязательно

    Список областей действия OAuth2, которые нужно запросить.

    Если поле scopes присутствует, оно переопределяет список областей действия, указанных в файле manifest.json.

WebAuthFlowDetails

Свойства

  • abortOnLoadForNonInteractive

    Логическое значение (необязательно)

    Chrome 113 и более поздние версии browser.* начиная с Chrome 148

    Указывает, нужно ли прекращать работу launchWebAuthFlow для неинтерактивных запросов после загрузки страницы. Этот параметр не влияет на интерактивные процессы.

    Если задано значение true (по умолчанию), процесс завершится сразу после загрузки страницы. Если задано значение false, процесс завершится только после того, как пройдет timeoutMsForNonInteractive. Это полезно для поставщиков идентификационной информации, которые используют JavaScript для переадресации после загрузки страницы.

  • интерактивный

    Логическое значение (необязательно)

    Запускать ли процесс аутентификации в интерактивном режиме.

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

    Если для параметра interactive задано значение true, окно будет показано после загрузки страницы. Если флаг имеет значение false или опущен, launchWebAuthFlow вернет ошибку, если начальная навигация не завершит процесс.

    Для процессов, в которых переадресация выполняется с помощью JavaScript, можно задать для параметра abortOnLoadForNonInteractive значение false и настроить параметр timeoutMsForNonInteractive, чтобы на странице выполнялась переадресация.

  • timeoutMsForNonInteractive

    number (необязательно)

    Chrome 113+ browser.* начиная с Chrome 148

    Максимальное время в миллисекундах, в течение которого launchWebAuthFlow может работать в неинтерактивном режиме. Действует, только если для параметра interactive задано значение false.

  • url

    string

    URL, который инициирует процесс аутентификации.

Методы

clearAllCachedAuthTokens()

Chrome 87 и более поздних версий browser.* начиная с Chrome 148 
browser.identity.clearAllCachedAuthTokens(): Promise<void>

Сбрасывает состояние Identity API:

  • Удаляет все токены доступа OAuth2 из кеша токенов.
  • Удаляет настройки аккаунта пользователя.
  • Отменяет авторизацию пользователя во всех потоках авторизации.

Возвраты

  • Promise<void>

    Chrome 106+ browser.* начиная с Chrome 148

    Возвращает объект Promise, который распознается, когда состояние очищено.

getAccounts()

Канал для разработчиков 
browser.identity.getAccounts(): Promise<AccountInfo[]>

Получает список объектов AccountInfo, описывающих аккаунты в профиле.

getAccounts поддерживается только в канале для разработчиков.

Возвраты

getAuthToken()

browser.identity.getAuthToken(
  details?: TokenDetails,
): Promise<GetAuthTokenResult>

Получает токен доступа OAuth2, используя идентификатор клиента и области действия, указанные в разделе oauth2 файла manifest.json.

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

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

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

Параметры

  • подробные сведения

    TokenDetails необязательно

    Параметры токена.

Возвраты

  • Chrome 105+ browser.* начиная с Chrome 148

    Возвращает объект Promise, который распознается с токеном доступа OAuth2, как указано в манифесте, или отклоняется в случае ошибки. Параметр grantedScopes заполняется начиная с Chrome 87. Если доступен, этот параметр содержит список предоставленных областей действия, соответствующих возвращенному токену.

getProfileUserInfo()

browser.identity.getProfileUserInfo(
  details?: ProfileDetails,
): Promise<ProfileUserInfo>

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

Требуется разрешение манифеста identity.email. В противном случае возвращается пустой результат.

Этот API отличается от identity.getAccounts двумя особенностями. Возвращаемая информация доступна в офлайн-режиме и относится только к основному аккаунту профиля.

Параметры

  • подробные сведения

    ProfileDetails необязательно

    Chrome 84+ browser.* начиная с Chrome 148

    Настройки профиля.

Возвраты

  • Promise<ProfileUserInfo>

    Chrome 106+ browser.* начиная с Chrome 148

    Возвращает Promise, который разрешается с ProfileUserInfo основного аккаунта Chrome, или пустой ProfileUserInfo, если аккаунт с указанным details не существует.

getRedirectURL()

browser.identity.getRedirectURL(
  path?: string,
): string

Создает URL переадресации для использования в launchWebAuthFlow.

Сгенерированные URL соответствуют шаблону https://<app-id>.chromiumapp.org/*.

Параметры

  • путь

    Строка (необязательно)

    Путь, добавленный в конец сгенерированного URL.

Возвраты

  • string

launchWebAuthFlow()

browser.identity.launchWebAuthFlow(
  details: WebAuthFlowDetails,
): Promise<string | undefined>

Запускает процесс аутентификации по указанному URL.

Этот метод позволяет использовать потоки аутентификации со сторонними поставщиками идентификационной информации. Для этого запускается веб-просмотр и выполняется переход по первому URL в потоке аутентификации поставщика. Когда поставщик перенаправляет на URL, соответствующий шаблону https://<app-id>.chromiumapp.org/*, окно закрывается, а конечный URL перенаправления передается функции callback.

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

Параметры

  • подробные сведения

    WebAuthFlowDetails

    Параметры процесса WebAuth.

Возвраты

  • Promise<string | undefined>

    Chrome 106 и более поздних версий browser.* начиная с Chrome 148

    Возвращает объект Promise, который распознается как URL, перенаправляющий обратно в ваше приложение.

removeCachedAuthToken()

browser.identity.removeCachedAuthToken(
  details: InvalidTokenDetails,
): Promise<void>

Удаляет токен доступа OAuth2 из кеша токенов Identity API.

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

Параметры

  • подробные сведения

    InvalidTokenDetails

    Информация о токене.

Возвраты

  • Promise<void>

    Chrome 106+ browser.* начиная с Chrome 148

    Возвращает объект Promise, который распознается, когда токен удален из кеша.

События

onSignInChanged

browser.identity.onSignInChanged.addListener(
  callback: function,
)

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

Параметры

  • обратный вызов

    function

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

    (account: AccountInfo, signedIn: boolean) => void

    • аккаунт

      AccountInfo

    • signedIn

      Логическое значение