Libreria JavaScript di autorizzazione di terze parti di Google per i siti web: riferimento API

Questo riferimento descrive l'API della libreria JavaScript di autorizzazione di Google 3P, che puoi utilizzare per caricare i codici di autorizzazione o accedere ai token da Google.

Metodo: google.accounts.oauth2.initCodeClient

Il metodo initCodeClient inizializza e restituisce un client di codice, con le configurazioni nel parametro.

google.accounts.oauth2.initCodeClient(config: CodeClientConfig)

Tipo di dati: CodeClientConfig

La tabella seguente elenca le proprietà del tipo di dati CodeClientConfig.

Proprietà
client_id Obbligatorio. L'ID client della tua applicazione. Questo valore è disponibile nella Console API.
scope Obbligatorio. Un elenco di ambiti delimitati da spazi che identificano le risorse a cui la tua applicazione potrebbe accedere per conto dell'utente. Questi valori definiscono la schermata per il consenso che Google mostra all'utente.
include_granted_scopes Facoltativo, il valore predefinito è true. Consente alle applicazioni di utilizzare l'autorizzazione incrementale per richiedere l'accesso ad ambiti aggiuntivi nel contesto. Se imposti il valore di questo parametro su false e la richiesta di autorizzazione viene concessa, il nuovo token di accesso coprirà solo gli ambiti per cui scope ha richiesto in questo CodeClientConfig.
redirect_uri Obbligatorio per l'esperienza utente di reindirizzamento. Determina dove il server API reindirizza l'utente dopo che l'utente ha completato il flusso di autorizzazione. Il valore deve corrispondere esattamente a uno degli URI di reindirizzamento autorizzati per il client OAuth 2.0 che hai configurato nella console dell'API e deve essere conforme alle nostre regole di convalida dell'URI di reindirizzamento. La proprietà verrà ignorata dall'esperienza utente popup.
callback Obbligatorio per l'UX popup. La funzione JavaScript che gestisce la risposta del codice restituito. La proprietà verrà ignorata dall'esperienza utente di reindirizzamento.
state Campo facoltativo. Consigliato per l'esperienza utente di reindirizzamento. Specifica qualsiasi valore di stringa utilizzato dall'applicazione per mantenere lo stato tra la richiesta di autorizzazione e la risposta del server di autorizzazione.
enable_serial_consent Facoltativo, il valore predefinito è true. Se è impostata su false, le autorizzazioni dell'Account Google più granulari verranno disattivate per gli ID client OAuth creati prima del 2019. Non è previsto alcun effetto per gli ID client OAuth più recenti, poiché sono sempre attive autorizzazioni più granulari.
login_hint Campo facoltativo. Se la tua applicazione sa quale utente deve autorizzare la richiesta, può utilizzare questa proprietà per fornire un suggerimento di accesso a Google. In caso di esito positivo, la selezione dell'account viene ignorata. L'indirizzo email o il valore del campo sotto token ID per l'utente di destinazione. Per ulteriori informazioni, vedi il campo login_hint nella documentazione di OpenID Connect.
hd Campo facoltativo. Se la tua applicazione conosce il dominio Workspace a cui appartiene l'utente, utilizzalo per fornire un suggerimento a Google. Se l'operazione ha esito positivo, gli account utente sono limitati o preselezionati per il dominio fornito. Per ulteriori informazioni, vedi il campo hd nella documentazione di OpenID Connect.
ux_mode Campo facoltativo. La modalità UX da utilizzare per il flusso di autorizzazione. Per impostazione predefinita, il flusso di consenso viene aperto in un popup. I valori validi sono popup e redirect.
select_account Facoltativo, il valore predefinito è 'false'. Valore booleano per richiedere all'utente di selezionare un account.
error_callback Campo facoltativo. La funzione JavaScript che gestisce alcuni errori non OAuth, come la finestra popup, non si apre o che si chiude prima che venga restituita una risposta OAuth.

Il campo "tipo" del parametro di input fornisce il motivo dettagliato.
  • Popup_failed_to_open Impossibile aprire la finestra popup.
  • Popup_closed La finestra popup viene chiusa prima che venga restituita una risposta OAuth.
  • unknown segnaposto per altri errori.

Tipo di dati: CodeClient

La classe ha un solo metodo di richiestaCode pubblico, che avvia il flusso OAuth 2.0 del codice UX.

interface CodeClient {
  requestCode(): void;
}

Tipo di dati: CodeResponse

Un oggetto JavaScript CodeResponse verrà passato al metodo callback nell'UX popup. Nell'esperienza utente di reindirizzamento, CodeResponse verrà passato come parametro URL.

La tabella seguente elenca le proprietà del tipo di dati CodeResponse.

Proprietà
code Il codice di autorizzazione di una risposta token corretta.
scope Un elenco di ambiti delimitato da spazi approvati dall'utente.
state Il valore stringa che l'applicazione utilizza per mantenere lo stato tra la richiesta di autorizzazione e la risposta.
error Un singolo codice di errore ASCII.
error_description Testo ASCII leggibile dall'uomo che fornisce informazioni aggiuntive, utilizzato per aiutare lo sviluppatore client a comprendere l'errore che si è verificato.
error_uri Un URI che identifica una pagina web leggibile con informazioni sull'errore, utilizzata per fornire allo sviluppatore del client informazioni aggiuntive sull'errore.

Metodo: google.accounts.oauth2.initTokenClient

Il metodo initTokenClient inizializza e restituisce un client token, con le configurazioni nel parametro.

google.accounts.oauth2.initTokenClient(config: TokenClientConfig)

Tipo di dati: TokenClientConfig

La tabella seguente elenca le proprietà del tipo di dati TokenClientConfig.

Proprietà
client_id Obbligatorio. L'ID client della tua applicazione. Questo valore è disponibile nella Console API.
callback Obbligatorio. La funzione JavaScript che gestisce la risposta del token restituito.
scope Obbligatorio. Un elenco di ambiti delimitati da spazi che identificano le risorse a cui la tua applicazione potrebbe accedere per conto dell'utente. Questi valori definiscono la schermata per il consenso che Google mostra all'utente.
include_granted_scopes Facoltativo, il valore predefinito è true. Consente alle applicazioni di utilizzare l'autorizzazione incrementale per richiedere l'accesso ad ambiti aggiuntivi nel contesto. Se imposti il valore di questo parametro su false e la richiesta di autorizzazione viene concessa, il nuovo token di accesso coprirà solo gli ambiti per cui scope ha richiesto in questo TokenClientConfig.
prompt Facoltativo, il valore predefinito è 'select_account'. Un elenco di prompt (sensibili alle maiuscole) che presentano l'utente. I valori possibili sono:
  • stringa vuota All'utente verrà richiesto soltanto il primo accesso all'app. Non può essere specificato con altri valori.
  • "none" non mostra alcuna schermata di autenticazione o di consenso. Non deve essere specificato con altri valori.
  • 'consent' Richiedi all'utente il consenso.
  • 'select_account' Richiedi all'utente di selezionare un account.
enable_serial_consent Facoltativo, il valore predefinito è true. Se è impostata su false, le autorizzazioni dell'Account Google più granulari verranno disattivate per gli ID client OAuth creati prima del 2019. Non è previsto alcun effetto per gli ID client OAuth più recenti, poiché sono sempre attive autorizzazioni più granulari.
login_hint Campo facoltativo. Se la tua applicazione sa quale utente deve autorizzare la richiesta, può utilizzare questa proprietà per fornire un suggerimento di accesso a Google. In caso di esito positivo, la selezione dell'account viene ignorata. L'indirizzo email o il valore del campo sotto token ID per l'utente di destinazione. Per ulteriori informazioni, vedi il campo login_hint nella documentazione di OpenID Connect.
hd Campo facoltativo. Se la tua applicazione conosce il dominio Workspace a cui appartiene l'utente, utilizzalo per fornire un suggerimento a Google. Se l'operazione ha esito positivo, gli account utente sono limitati o preselezionati per il dominio fornito. Per ulteriori informazioni, vedi il campo hd nella documentazione di OpenID Connect.
state Campo facoltativo. Non consigliati. Specifica qualsiasi valore di stringa utilizzato dall'applicazione per mantenere lo stato tra la richiesta di autorizzazione e la risposta del server di autorizzazione.
error_callback Campo facoltativo. La funzione JavaScript che gestisce alcuni errori non OAuth, come la finestra popup, non si apre o che si chiude prima che venga restituita una risposta OAuth.

Il campo "tipo" del parametro di input fornisce il motivo dettagliato.
  • Popup_failed_to_open Impossibile aprire la finestra popup.
  • Popup_closed La finestra popup viene chiusa prima che venga restituita una risposta OAuth.
  • unknown segnaposto per altri errori.

Tipo di dati: TokenClient

La classe ha un solo metodo pubblico requestAccessToken, che avvia il flusso dell'esperienza utente del token OAuth 2.0.

interface TokenClient {
  requestAccessToken(overrideConfig?: OverridableTokenClientConfig): void;
}
Argomenti
overrideConfig OverClientableTokenClientConfig Campo facoltativo. Le configurazioni da sostituire in questo metodo.

Tipo di dati: OverridableTokenClientConfig

La tabella seguente elenca le proprietà del tipo di dati OverridableTokenClientConfig.

Proprietà
scope Campo facoltativo. Un elenco di ambiti delimitati da spazi che identificano le risorse a cui la tua applicazione potrebbe accedere per conto dell'utente. Questi valori determinano la schermata per il consenso che Google mostra all'utente.
include_granted_scopes Facoltativo, il valore predefinito è true. Consente alle applicazioni di utilizzare l'autorizzazione incrementale per richiedere l'accesso ad ambiti aggiuntivi nel contesto. Se imposti il valore di questo parametro su false e la richiesta di autorizzazione viene concessa, il nuovo token di accesso coprirà solo gli ambiti per cui scope ha richiesto in questo OverridableTokenClientConfig.
prompt Campo facoltativo. Un elenco di messaggi, sensibili alle maiuscole, che presentano la presenza dell'utente.
enable_serial_consent Facoltativo, il valore predefinito è true. Se è impostata su false, le autorizzazioni dell'Account Google più granulari verranno disattivate per gli ID client OAuth creati prima del 2019. Non è previsto alcun effetto per gli ID client OAuth più recenti, poiché sono sempre attive autorizzazioni più granulari.
login_hint Campo facoltativo. Se la tua applicazione sa quale utente deve autorizzare la richiesta, può utilizzare questa proprietà per fornire un suggerimento di accesso a Google. In caso di esito positivo, la selezione dell'account viene ignorata. L'indirizzo email o il valore del campo sotto token ID per l'utente di destinazione. Per ulteriori informazioni, vedi il campo login_hint nella documentazione di OpenID Connect.
state Campo facoltativo. Non consigliati. Specifica qualsiasi valore di stringa utilizzato dall'applicazione per mantenere lo stato tra la richiesta di autorizzazione e la risposta del server di autorizzazione.

Tipo di dati: TokenResponse

Un oggetto JavaScript TokenResponse verrà passato al metodo di callback nell'esperienza utente popup.

La tabella seguente elenca le proprietà del tipo di dati TokenResponse.

Proprietà
access_token Il token di accesso di una risposta al token riuscita.
expires_in La durata in secondi del token di accesso.
hd Il dominio ospitato a cui appartiene l'utente che ha eseguito l'accesso.
prompt Il valore prompt utilizzato dal possibile elenco di valori specificati da TokenClientConfig o OverridableTokenClientConfig.
token_type Il tipo di token emesso.
scope Un elenco di ambiti delimitato da spazi approvati dall'utente.
state Il valore stringa che l'applicazione utilizza per mantenere lo stato tra la richiesta di autorizzazione e la risposta.
error Un singolo codice di errore ASCII.
error_description Testo ASCII leggibile dall'uomo che fornisce informazioni aggiuntive, utilizzato per aiutare lo sviluppatore client a comprendere l'errore che si è verificato.
error_uri Un URI che identifica una pagina web leggibile con informazioni sull'errore, utilizzata per fornire allo sviluppatore del client informazioni aggiuntive sull'errore.

Metodo: google.accounts.oauth2.hasGrantedAllScopes

Verifica se l'utente ha concesso tutti gli ambiti specificati.

google.accounts.oauth2.hasGrantedAllScopes(
                                            tokenResponse: TokenResponse,
                                            firstScope: string, ...restScopes: string[]
                                          ): boolean;
Argomenti
tokenResponse TokenResponse Obbligatorio. Un oggetto TokenResponse.
firstScope stringa Obbligatorio. L'ambito da verificare.
restScopes stringa[] Campo facoltativo. Altri ambiti da controllare.
Valori restituiti
boolean Vero se tutti gli ambiti sono concessi.

Metodo: google.accounts.oauth2.hasGranted AnyScope

Verifica se l'utente ha concesso uno o più ambiti specificati.

google.accounts.oauth2.hasGrantedAnyScope(
                                           tokenResponse: TokenResponse,
                                           firstScope: string, ...restScopes: string[]
                                         ): boolean;
Argomenti
tokenResponse TokenResponse Obbligatorio. Un oggetto TokenResponse.
firstScope stringa Obbligatorio. L'ambito da verificare.
restScopes stringa[] Campo facoltativo. Altri ambiti da controllare.
Valori restituiti
boolean True se viene concesso uno qualsiasi degli ambiti.

Metodo: google.accounts.oauth2.revoke

Il metodo revoke revoca tutti gli ambiti che l'utente ha concesso all'app. Per revocare l'autorizzazione è necessario un token di accesso valido.

google.accounts.oauth2.revoke(accessToken: string, done: () => void): void;
Argomenti
accessToken stringa Obbligatorio. Un token di accesso valido.
callback funzione Campo facoltativo. Gestore RevocationResponse.

Tipo di dati: RevocationResponse

Un oggetto JavaScript RevocationResponse verrà passato al metodo di callback.

La tabella seguente elenca le proprietà del tipo di dati RevocationResponse.

Proprietà
successful Booleano. true attivato, false completato in caso di errore.
error Stringa. Non definita sul successo. Un singolo codice di errore ASCII. Sono inclusi, a titolo esemplificativo, i codici di errore OAuth 2.0 standard. Errori comuni per il metodo revoke:
  • invalid_token: il token è già scaduto o è stato revocato prima della chiamata del metodo revoke. Nella maggior parte dei casi, la richiesta associata a accessToken viene revocata.
  • invalid_request: il token non è revocabile. Assicurati che accessToken sia una credenziale di Google OAuth 2.0 valida.
error_description Stringa. Non definita sul successo. Il testo ASCII leggibile può fornire ulteriori informazioni sulla proprietà error. Gli sviluppatori possono utilizzarla per comprendere meglio l'errore che si è verificato. La stringa error_description è solo in inglese. Per gli errori comuni elencati in error, l'elemento error_description corrispondente:
  • invalid_token - Il token è scaduto o è stato revocato.
  • invalid_request: il token non è revocabile.