browser.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 para la cuenta. Este ID no cambiará durante la vida útil de la cuenta.

AccountStatus

Chrome 84 y versiones posteriores browser.* desde Chrome 148

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 browser.* desde Chrome 148

Propiedades

  • grantedScopes

    string[] opcional

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

  • token

    string opcional

    Es el token específico asociado con la solicitud.

InvalidTokenDetails

Propiedades

  • token

    string

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

ProfileDetails

Chrome 84 y versiones posteriores browser.* desde Chrome 148

Propiedades

  • accountStatus

    AccountStatus opcional

    Es el estado de la cuenta principal que accedió a un perfil cuyo ProfileUserInfo se debe devolver. La configuración predeterminada es el estado de la cuenta SYNC.

ProfileUserInfo

Propiedades

  • correo electrónico

    string

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

  • id

    string

    Es un identificador único para la cuenta. Este ID no cambiará durante la vida útil de la cuenta. Está vacío si el usuario no accedió o (en M41+) no se especifica el permiso de manifiesto identity.email.

TokenDetails

Propiedades

  • cuenta

    AccountInfo opcional

    Es el ID de 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 browser.* desde Chrome 148

    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 se 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 indicará al usuario lo que debe hacer según sea necesario. Cuando la marca es false o se omite, getAuthToken devolverá un error cada vez que se requiera un mensaje.

  • permisos

    string[] opcional

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

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

WebAuthFlowDetails

Propiedades

  • abortOnLoadForNonInteractive

    booleano opcional

    Chrome 113 y versiones posteriores browser.* desde Chrome 148

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

    Cuando se establece en true (predeterminado), el flujo finalizará inmediatamente después de la carga de 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 autenticación en modo interactivo.

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

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

    En el caso de los flujos que usan JavaScript para el redireccionamiento, se puede establecer abortOnLoadForNonInteractive en false junto con la configuración de timeoutMsForNonInteractive para que la página pueda realizar los redireccionamientos.

  • timeoutMsForNonInteractive

    number opcional

    Chrome 113 y versiones posteriores browser.* desde Chrome 148

    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 autenticación.

Métodos

clearAllCachedAuthTokens()

Chrome 87 y versiones posteriores browser.* desde Chrome 148 
browser.identity.clearAllCachedAuthTokens(): 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 en todos los flujos de autenticación

Muestra

  • Promise<void>

    Chrome 106 y versiones posteriores browser.* desde Chrome 148

    Devuelve una promesa que se resuelve cuando se borra el estado.

getAccounts()

Canal para desarrolladores 
browser.identity.getAccounts(): Promise<AccountInfo[]>

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

getAccounts solo se admite en el canal para desarrolladores.

Muestra

getAuthToken()

browser.identity.getAuthToken(
  details?: TokenDetails,
): 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 puedes llamar a getAuthToken de forma no interactiva cada vez que se requiera un token. La caché de tokens controla automáticamente el vencimiento.

Para ofrecer una buena experiencia del usuario, es importante que las solicitudes de tokens interactivos se inicien desde la IU de tu app y que se explique para qué es la autorización. De lo contrario, los usuarios recibirán solicitudes de autorización o pantallas de acceso a Chrome si no accedieron, sin ningún contexto. En particular, no uses getAuthToken de forma interactiva cuando se inicie la 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 browser.* desde Chrome 148

    Devuelve una promesa que se resuelve con un token de acceso de OAuth2, según lo especificado por el manifiesto, o se rechaza si se produjo un error. El parámetro grantedScopes se propaga desde Chrome 87. Cuando está disponible, este parámetro contiene la lista de permisos otorgados que corresponden al token devuelto.

getProfileUserInfo()

browser.identity.getProfileUserInfo(
  details?: ProfileDetails,
): 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 de manifiesto identity.email. De lo contrario, devuelve un resultado vacío.

Esta API se diferencia de identity.getAccounts en dos aspectos. 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 browser.* desde Chrome 148

    Opciones de perfil.

Muestra

  • Promise<ProfileUserInfo>

    Chrome 106 y versiones posteriores browser.* desde Chrome 148

    Devuelve una promesa que se resuelve con el ProfileUserInfo de la cuenta principal de Chrome o un ProfileUserInfo vacío si no existe la cuenta con el details proporcionado.

getRedirectURL()

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

Genera una URL de redireccionamiento que se usará en launchWebAuthFlow.

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

Parámetros

  • ruta de acceso

    string opcional

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

Muestra

  • string

launchWebAuthFlow()

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

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

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

Para brindar una buena experiencia del usuario, es importante que los flujos de autenticación interactivos se inicien desde la IU de tu app y que se explique para qué sirve la autorización. De lo contrario, tus usuarios recibirán solicitudes de autorización sin contexto. En particular, no inicies un flujo de autenticación interactivo cuando se inicie la app por primera vez.

Parámetros

Muestra

  • Promise<string | undefined>

    Chrome 106 y versiones posteriores browser.* desde Chrome 148

    Devuelve una promesa que se resuelve con la URL redireccionada de vuelta a tu aplicación.

removeCachedAuthToken()

browser.identity.removeCachedAuthToken(
  details: InvalidTokenDetails,
): 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

Muestra

  • Promise<void>

    Chrome 106 y versiones posteriores browser.* desde Chrome 148

    Devuelve una promesa que se resuelve cuando se quita el token de la caché.

Eventos

onSignInChanged

browser.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