chrome.identity

Descripción

Usa la API de chrome.identity para obtener tokens de acceso de OAuth2.

Permisos

identity

Tipos

AccountInfo

Propiedades

  • id

    string

    Es un identificador único de la cuenta. Este ID no cambiará durante la vida útil de la cuenta.

AccountStatus

Chrome 84 y versiones posteriores

Enum

"SYNC"
Especifica que la sincronización está habilitada para la cuenta principal.

"ANY"
Especifica la existencia de una cuenta principal, si la hay.

GetAuthTokenResult

Chrome 105 y versiones posteriores

Propiedades

  • grantedScopes

    string[] opcional

    Es una lista de los permisos de OAuth2 otorgados a la extensión.

  • token

    cadena opcional

    Es el token específico asociado a la solicitud.

InvalidTokenDetails

Propiedades

  • token

    string

    Es el token específico que se debe quitar de la caché.

ProfileDetails

Chrome 84 y versiones posteriores

Propiedades

  • accountStatus

    AccountStatus opcional

    Es el estado de la cuenta principal que accedió a un perfil cuyo ProfileUserInfo se debe devolver. El valor predeterminado es el estado de la cuenta SYNC.

ProfileUserInfo

Propiedades

  • correo electrónico

    string

    Es la dirección de correo electrónico de la cuenta de usuario que accedió al perfil actual. Estará vacío si el usuario no accedió o si no se especificó el permiso de manifiesto identity.email.

  • id

    string

    Es un identificador único de la cuenta. Este ID no cambiará durante la vida útil de la cuenta. Estará vacío si el usuario no accedió o (en M41 y versiones posteriores) no se especificó el permiso de manifiesto identity.email.

TokenDetails

Propiedades

  • cuenta

    AccountInfo opcional

    Es el ID de la cuenta cuyo token se debe devolver. Si no se especifica, la función usará una cuenta del perfil de Chrome: la cuenta de sincronización, si hay una, o la primera cuenta web de Google.

  • enableGranularPermissions

    booleano opcional

    Chrome 87 y versiones posteriores

    La marca enableGranularPermissions permite que las extensiones habiliten de forma anticipada la pantalla de consentimiento de permisos detallados, en la que los permisos solicitados se otorgan o rechazan de forma individual.

  • interactive

    booleano opcional

    Para recuperar un token, es posible que el usuario deba acceder a Chrome o aprobar los permisos solicitados por la aplicación. Si la marca interactiva es true, getAuthToken le pedirá al usuario que realice las acciones necesarias. Cuando la marca es false o se omite, getAuthToken devolverá un error cada vez que se requiera una instrucción.

  • permisos

    string[] opcional

    Es una lista de permisos de OAuth2 que se solicitarán.

    Cuando el campo scopes está presente, anula la lista de alcances especificados en manifest.json.

WebAuthFlowDetails

Propiedades

  • abortOnLoadForNonInteractive

    booleano opcional

    Chrome 113 y versiones posteriores

    Indica si se debe finalizar launchWebAuthFlow para las solicitudes no interactivas después de que se cargue la página. Este parámetro no afecta los flujos interactivos.

    Cuando se establece en true (predeterminado), el flujo finalizará inmediatamente después de que se cargue la página. Cuando se establece en false, el flujo solo finalizará después de que pase el timeoutMsForNonInteractive. Esto es útil para los proveedores de identidad que usan JavaScript para realizar redireccionamientos después de que se carga la página.

  • interactive

    booleano opcional

    Indica si se debe iniciar el flujo de autorización en modo interactivo.

    Dado que algunos flujos de autorización pueden redireccionar de inmediato a una URL de resultado, launchWebAuthFlow oculta su vista web hasta que la primera navegación redirecciona a la URL final o termina de cargar una página que se debe mostrar.

    Si la marca interactive es true, la ventana se mostrará cuando se complete la carga de una página. Si la marca es false o se omite, launchWebAuthFlow devolverá un error si la navegación inicial no completa el flujo.

    En el caso de los flujos que usan JavaScript para el redireccionamiento, abortOnLoadForNonInteractive se puede establecer en false en combinación con el parámetro de configuración timeoutMsForNonInteractive para darle a la página la oportunidad de realizar cualquier redireccionamiento.

  • timeoutMsForNonInteractive

    número opcional

    Chrome 113 y versiones posteriores

    Es la cantidad máxima de tiempo, en milisegundos, que se permite que launchWebAuthFlow se ejecute en modo no interactivo en total. Solo tiene efecto si interactive es false.

  • url

    string

    Es la URL que inicia el flujo de autorización.

Métodos

clearAllCachedAuthTokens()

Promise Chrome 87 y versiones posteriores 
chrome.identity.clearAllCachedAuthTokens(
  callback?: function,
): Promise<void>

Restablece el estado de la API de Identity:

  • Quita todos los tokens de acceso de OAuth2 de la caché de tokens.
  • Quita las preferencias de la cuenta del usuario
  • Anula la autorización del usuario para todos los flujos de autenticación

Parámetros

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promise<void>

    Chrome 106 y versiones posteriores

    Las promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

getAccounts()

Promesa Canal para desarrolladores 
chrome.identity.getAccounts(
  callback?: function,
): Promise<AccountInfo[]>

Recupera una lista de objetos AccountInfo que describen las cuentas presentes en el perfil.

getAccounts solo se admite en el canal de desarrollo.

Parámetros

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (accounts: AccountInfo[]) => void

Muestra

  • Promise<AccountInfo[]>

    Las promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

getAuthToken()

Promesa 
chrome.identity.getAuthToken(
  details?: TokenDetails,
  callback?: function,
): Promise<GetAuthTokenResult>

Obtiene un token de acceso de OAuth2 con el ID de cliente y los permisos especificados en la sección oauth2 de manifest.json.

La API de Identity almacena en caché los tokens de acceso en la memoria, por lo que no hay problema en llamar a getAuthToken de forma no interactiva cada vez que se requiera un token. La caché de tokens controla automáticamente el vencimiento.

Para brindar una buena experiencia del usuario, es importante que la IU de tu app inicie las solicitudes de tokens interactivas y explique para qué se requiere la autorización. Si no lo haces, tus usuarios recibirán solicitudes de autorización o pantallas de acceso a Chrome (si no accedieron) sin contexto. En particular, no uses getAuthToken de forma interactiva cuando se inicie tu app por primera vez.

Nota: Cuando se llama con una devolución de llamada, en lugar de devolver un objeto, esta función devolverá las dos propiedades como argumentos separados que se pasan a la devolución de llamada.

Parámetros

Muestra

  • Chrome 105 y versiones posteriores

    Las promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

getProfileUserInfo()

Promesa 
chrome.identity.getProfileUserInfo(
  details?: ProfileDetails,
  callback?: function,
): Promise<ProfileUserInfo>

Recupera la dirección de correo electrónico y el ID de Gaia ofuscado del usuario que accedió a un perfil.

Requiere el permiso identity.email del manifiesto. De lo contrario, devuelve un resultado vacío.

Esta API se diferencia de identity.getAccounts de dos maneras. La información que se devuelve está disponible sin conexión y solo se aplica a la cuenta principal del perfil.

Parámetros

  • detalles

    ProfileDetails opcional

    Chrome 84 y versiones posteriores

    Opciones de perfil

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (userInfo: ProfileUserInfo) => void

Muestra

  • Promise<ProfileUserInfo>

    Chrome 106 y versiones posteriores

    Las promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

getRedirectURL()

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

Genera una URL de redireccionamiento para usar en launchWebAuthFlow.

Las URLs generadas coinciden con el patrón https://<app-id>.chromiumapp.org/*.

Parámetros

  • ruta de acceso

    cadena opcional

    Es la ruta de acceso que se agrega al final de la URL generada.

Muestra

  • string

launchWebAuthFlow()

Promesa 
chrome.identity.launchWebAuthFlow(
  details: WebAuthFlowDetails,
  callback?: function,
): Promise<string | undefined>

Inicia un flujo de autorización en la URL especificada.

Este método habilita los flujos de autorización con proveedores de identidad que no son de Google. Para ello, inicia una vista web y la navega a la primera URL del flujo de autorización del proveedor. Cuando el proveedor redirecciona a una URL que coincide con el patrón https://<app-id>.chromiumapp.org/*, la ventana se cierra y la URL de redireccionamiento final se pasa a la función callback.

Para brindar una buena experiencia del usuario, es importante que la IU de tu app inicie flujos de autorización interactivos que expliquen para qué se solicita la autorización. Si no lo haces, tus usuarios recibirán solicitudes de autorización sin contexto. En particular, no inicies un flujo de autorización interactivo cuando se inicie tu app por primera vez.

Parámetros

  • Son las opciones del flujo de WebAuth.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (responseUrl?: string) => void

    • responseUrl

      cadena opcional

Muestra

  • Promesa<cadena | undefined>

    Chrome 106 y versiones posteriores

    Las promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

removeCachedAuthToken()

Promesa 
chrome.identity.removeCachedAuthToken(
  details: InvalidTokenDetails,
  callback?: function,
): Promise<void>

Quita un token de acceso de OAuth2 de la caché de tokens de la API de Identity.

Si se descubre que un token de acceso no es válido, se debe pasar a removeCachedAuthToken para quitarlo de la caché. Luego, la app puede recuperar un token nuevo con getAuthToken.

Parámetros

  • Es la información del token.

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promise<void>

    Chrome 106 y versiones posteriores

    Las promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

Eventos

onSignInChanged

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

Se activa cuando cambia el estado de acceso de una cuenta en el perfil del usuario.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

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