browser.identity

Descrizione

Utilizza l'API chrome.identity per ottenere i token di accesso OAuth2.

Autorizzazioni

identity

Tipi

AccountInfo

Proprietà

  • id

    stringa

    Un identificatore univoco dell'account. Questo ID non cambierà per tutta la durata dell'account.

AccountStatus

Chrome 84+ browser.* da Chrome 148

Enum

"SYNC"
Specifica che la sincronizzazione è attiva per l'account principale.

"ANY"
Specifica l'esistenza di un account principale, se presente.

GetAuthTokenResult

Chrome 105 e versioni successive browser.* da Chrome 148

Proprietà

  • grantedScopes

    string[] facoltativo

    Un elenco di ambiti OAuth2 concessi all'estensione.

  • token

    stringa facoltativa

    Il token specifico associato alla richiesta.

InvalidTokenDetails

Proprietà

  • token

    stringa

    Il token specifico che deve essere rimosso dalla cache.

ProfileDetails

Chrome 84+ browser.* da Chrome 148

Proprietà

  • accountStatus

    AccountStatus facoltativo

    Lo stato dell'account principale che ha eseguito l'accesso a un profilo di cui deve essere restituito ProfileUserInfo. Il valore predefinito è lo stato dell'account SYNC.

ProfileUserInfo

Proprietà

  • email

    stringa

    Un indirizzo email per l'account utente che ha eseguito l'accesso al profilo corrente. Vuoto se l'utente non ha eseguito l'accesso o se l'autorizzazione del manifest identity.email non è specificata.

  • id

    stringa

    Un identificatore univoco dell'account. Questo ID non cambierà per tutta la durata dell'account. Vuoto se l'utente non ha eseguito l'accesso o (in M41+) non è specificata l'autorizzazione del file manifest identity.email.

TokenDetails

Proprietà

  • account

    AccountInfo facoltativo

    L'ID account di cui deve essere restituito il token. Se non viene specificato, la funzione utilizzerà un account del profilo Chrome: l'account di sincronizzazione, se presente, o il primo Account Google web.

  • enableGranularPermissions

    boolean facoltativo

    Chrome 87 e versioni successive browser.* da Chrome 148

    Il flag enableGranularPermissions consente alle estensioni di attivare in anticipo la schermata per il consenso alle autorizzazioni granulari, in cui le autorizzazioni richieste vengono concesse o negate singolarmente.

  • interattivo

    boolean facoltativo

    Il recupero di un token potrebbe richiedere all'utente di accedere a Chrome o di approvare gli ambiti richiesti dall'applicazione. Se il flag interattivo è true, getAuthToken chiederà all'utente di intervenire, se necessario. Quando il flag è false o viene omesso, getAuthToken restituirà un errore ogni volta che è richiesto un prompt.

  • ambiti

    string[] facoltativo

    Un elenco di ambiti OAuth2 da richiedere.

    Se è presente il campo scopes, questo sostituisce l'elenco di ambiti specificato in manifest.json.

WebAuthFlowDetails

Proprietà

  • abortOnLoadForNonInteractive

    boolean facoltativo

    Chrome 113+ browser.* da Chrome 148

    Indica se terminare launchWebAuthFlow per le richieste non interattive dopo il caricamento della pagina. Questo parametro non influisce sui flussi interattivi.

    Se impostato su true (valore predefinito), il flusso terminerà immediatamente dopo il caricamento della pagina. Se impostato su false, il flusso termina solo dopo il passaggio di timeoutMsForNonInteractive. Questa opzione è utile per i provider di identità che utilizzano JavaScript per eseguire i reindirizzamenti dopo il caricamento della pagina.

  • interattivo

    boolean facoltativo

    Indica se avviare il flusso di autenticazione in modalità interattiva.

    Poiché alcuni flussi di autenticazione potrebbero reindirizzare immediatamente a un URL dei risultati, launchWebAuthFlow nasconde la visualizzazione web finché la prima navigazione non reindirizza all'URL finale o non termina il caricamento di una pagina destinata alla visualizzazione.

    Se il flag interactive è true, la finestra verrà visualizzata al termine del caricamento della pagina. Se il flag è false o viene omesso, launchWebAuthFlow restituirà un errore se la navigazione iniziale non completa il flusso.

    Per i flussi che utilizzano JavaScript per il reindirizzamento, abortOnLoadForNonInteractive può essere impostato su false in combinazione con l'impostazione timeoutMsForNonInteractive per consentire alla pagina di eseguire eventuali reindirizzamenti.

  • timeoutMsForNonInteractive

    number optional

    Chrome 113+ browser.* da Chrome 148

    Il tempo massimo, in millisecondi, per cui launchWebAuthFlow può essere eseguito in modalità non interattiva in totale. Ha effetto solo se interactive è false.

  • url

    stringa

    L'URL che avvia il flusso di autenticazione.

Metodi

clearAllCachedAuthTokens()

Chrome 87 e versioni successive browser.* da Chrome 148 
browser.identity.clearAllCachedAuthTokens(): Promise<void>

Reimposta lo stato dell'API Identity:

  • Rimuove tutti i token di accesso OAuth2 dalla cache dei token
  • Rimuove le preferenze dell'account dell'utente
  • Revoca l'autorizzazione dell'utente da tutti i flussi di autenticazione

Resi

  • Promise<void>

    Chrome 106+ browser.* da Chrome 148

    Restituisce una Promise che si risolve quando lo stato è stato cancellato.

getAccounts()

Canale Dev 
browser.identity.getAccounts(): Promise<AccountInfo[]>

Recupera un elenco di oggetti AccountInfo che descrivono gli account presenti nel profilo.

getAccounts è supportato solo sul canale Dev.

Resi

getAuthToken()

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

Recupera un token di accesso OAuth2 utilizzando l'ID client e gli ambiti specificati nella sezione oauth2 di manifest.json.

L'API Identity memorizza nella cache i token di accesso, quindi puoi chiamare getAuthToken in modo non interattivo ogni volta che è richiesto un token. La cache dei token gestisce automaticamente la scadenza.

Per un'esperienza utente ottimale, è importante che le richieste di token interattive vengano avviate dalla UI della tua app, spiegando a cosa serve l'autorizzazione. In caso contrario, gli utenti riceveranno richieste di autorizzazione o schermate di accesso a Chrome se non hanno eseguito l'accesso, senza contesto. In particolare, non utilizzare getAuthToken in modo interattivo al primo avvio dell'app.

Nota: se chiamata con un callback, anziché restituire un oggetto, questa funzione restituirà le due proprietà come argomenti separati passati al callback.

Parametri

Resi

  • Chrome 105 e versioni successive browser.* da Chrome 148

    Restituisce una Promise che si risolve con un token di accesso OAuth2 come specificato dal manifest o rifiuta se si è verificato un errore. Il parametro grantedScopes viene compilato a partire da Chrome 87. Se disponibile, questo parametro contiene l'elenco degli ambiti concessi corrispondenti al token restituito.

getProfileUserInfo()

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

Recupera l'indirizzo email e l'ID GAIA offuscato dell'utente che ha eseguito l'accesso a un profilo.

Richiede l'autorizzazione del manifest identity.email. In caso contrario, restituisce un risultato vuoto.

Questa API è diversa da identity.getAccounts in due modi. Le informazioni restituite sono disponibili offline e si applicano solo all'account principale del profilo.

Parametri

  • dettagli

    ProfileDetails facoltativo

    Chrome 84+ browser.* da Chrome 148

    Opzioni del profilo.

Resi

  • Promise<ProfileUserInfo>

    Chrome 106+ browser.* da Chrome 148

    Restituisce una Promise che si risolve con l'ProfileUserInfo dell'account Chrome principale o con un ProfileUserInfo vuoto se l'account con l'details specificato non esiste.

getRedirectURL()

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

Genera un URL di reindirizzamento da utilizzare in launchWebAuthFlow.

Gli URL generati corrispondono al pattern https://<app-id>.chromiumapp.org/*.

Parametri

  • percorso

    stringa facoltativa

    Il percorso aggiunto alla fine dell'URL generato.

Resi

  • stringa

launchWebAuthFlow()

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

Avvia un flusso di autenticazione all'URL specificato.

Questo metodo attiva i flussi di autenticazione con provider di identità non Google avviando una visualizzazione web e indirizzandola al primo URL nel flusso di autenticazione del provider. Quando il provider reindirizza a un URL corrispondente al pattern https://<app-id>.chromiumapp.org/*, la finestra si chiude e l'URL di reindirizzamento finale viene passato alla funzione callback.

Per un'esperienza utente ottimale, è importante che i flussi di autenticazione interattivi vengano avviati dalla UI della tua app, spiegando a cosa serve l'autorizzazione. In caso contrario, i tuoi utenti riceveranno richieste di autorizzazione senza contesto. In particolare, non avviare un flusso di autenticazione interattivo al primo avvio dell'app.

Parametri

Resi

  • Promise<string | undefined>

    Chrome 106+ browser.* da Chrome 148

    Restituisce una Promise che si risolve con l'URL reindirizzato alla tua applicazione.

removeCachedAuthToken()

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

Rimuove un token di accesso OAuth2 dalla cache dei token dell'API Identity.

Se un token di accesso risulta non valido, deve essere passato a removeCachedAuthToken per rimuoverlo dalla cache. L'app potrebbe quindi recuperare un nuovo token con getAuthToken.

Parametri

Resi

  • Promise<void>

    Chrome 106+ browser.* da Chrome 148

    Restituisce una Promise che si risolve quando il token viene rimosso dalla cache.

Eventi

onSignInChanged

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

Attivato quando lo stato di accesso cambia per un account nel profilo dell'utente.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

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