Libreria JavaScript dell'autorizzazione di terze parti di Google per i siti web - Riferimento API

Questo riferimento descrive l'API della libreria JavaScript di autorizzazione di terze parti di Google, che puoi utilizzare per caricare i codici di autorizzazione o i token di accesso di 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 seguente tabella elenca le proprietà del tipo di dati CodeClientConfig.

Proprietà
client_id Obbligatorio. L'ID client della tua applicazione. Puoi trovare questo valore nella console API.
scope Obbligatorio. Un elenco di ambiti delimitati da spazi che identificano le risorse a cui l'applicazione potrebbe accedere per conto dell'utente. Questi valori determinano la schermata di 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 approvata, il nuovo token di accesso coprirà solo gli ambiti a cui scope ha richiesto in questo CodeClientConfig.
redirect_uri Obbligatorio per il reindirizzamento dell'UX. Determina dove il server API reindirizza l'utente dopo che l'utente completa 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 API e che deve essere conforme alle nostre Regole di convalida dell'URI di reindirizzamento. La proprietà verrà ignorata dall'UX popup.
callback Necessaria per l'UX popup. La funzione JavaScript che gestisce la risposta del codice restituita. La proprietà verrà ignorata dall'UX di reindirizzamento.
state Campo facoltativo. Opzione consigliata per il reindirizzamento dell'UX. Specifica qualsiasi valore stringa utilizzato dall'applicazione per mantenere lo stato tra la richiesta di autorizzazione e la risposta del server di autorizzazione.
enable_granular_consent (Facoltativo) Il valore predefinito è true. Se viene impostata su false, le autorizzazioni più granulari dell'Account Google verrebbero disattivate per gli ID client OAuth creati prima del 2019. Se vengono impostati entrambi i valori enable_granular_consent e enable_serial_consent, viene applicato solo il valore enable_granular_consent, mentre il valore enable_serial_consent viene ignorato.

Nessun effetto per gli ID client OAuth più recenti, poiché per questi ultimi sono sempre attive autorizzazioni più granulari.
enable_serial_consent Deprecata. Devi usare enable_granular_consent. Ha lo stesso effetto di enable_granular_consent. Le applicazioni esistenti che utilizzano enable_serial_consent possono continuare a farlo, ma ti invitiamo ad aggiornare il tuo codice per utilizzare enable_granular_consent nel prossimo aggiornamento dell'applicazione.
login_hint Campo facoltativo. Se l'applicazione sa quale utente deve autorizzare la richiesta, può utilizzare questa proprietà per fornire un suggerimento di accesso a Google. Se l'operazione va a buon fine, la selezione dell'account viene saltata. Il valore del campo indirizzo email o token ID sub 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, usalo per fornire un suggerimento a Google. Se l'operazione va a buon fine, gli account utente vengono preselezionati o limitati 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, si aprirà il flusso di consenso in un popup. I valori validi sono popup e redirect.
select_account Facoltativo, il valore predefinito è 'false'. Valore booleano che richiede all'utente di selezionare un account.
error_callback Campo facoltativo. La funzione JavaScript che gestisce alcuni errori non OAuth, ad esempio la finestra popup non si apre o viene chiusa prima che venga restituita una risposta OAuth.

Il campo "type" 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.
  • sconosciuto Segnaposto per altri errori.

Tipo di dati: CodeClient

La classe ha un solo metodo pubblico requestCode, che avvia il flusso UX per il codice OAuth 2.0.

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 parametri URL.

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

Proprietà
code Il codice di autorizzazione di una risposta del token riuscita.
scope Un elenco delimitato da spazi di ambiti 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 che fornisce informazioni aggiuntive, utilizzato per aiutare lo sviluppatore del client a comprendere l'errore che si è verificato.
error_uri Un URI che identifica una pagina web leggibile con informazioni sull'errore, utilizzato 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 seguente tabella elenca le proprietà del tipo di dati TokenClientConfig.

Proprietà
client_id Obbligatorio. L'ID client della tua applicazione. Puoi trovare questo valore nella console API.
callback Obbligatorio. La funzione JavaScript che gestisce la risposta token restituita.
scope Obbligatorio. Un elenco di ambiti delimitati da spazi che identificano le risorse a cui l'applicazione potrebbe accedere per conto dell'utente. Questi valori determinano la schermata di 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 approvata, il nuovo token di accesso coprirà solo gli ambiti a cui scope ha richiesto in questo TokenClientConfig.
prompt (Facoltativo) Il valore predefinito è 'select_account'. Un elenco di prompt, delimitati da spazi e sensibili alle maiuscole, da presentare all'utente. I valori possibili sono:
  • stringa vuota L'utente riceverà una richiesta di accesso solo la prima volta che la tua app richiede l'accesso. Non può essere specificato con altri valori.
  • "nessuna": non consente di visualizzare le schermate di autenticazione o di consenso. Non deve essere specificato con altri valori.
  • 'consent' Chiede il consenso all'utente.
  • 'select_account' Chiede all'utente di selezionare un account.
enable_granular_consent (Facoltativo) Il valore predefinito è true. Se viene impostata su false, le autorizzazioni più granulari dell'Account Google verrebbero disattivate per gli ID client OAuth creati prima del 2019. Se vengono impostati entrambi i valori enable_granular_consent e enable_serial_consent, viene applicato solo il valore enable_granular_consent, mentre il valore enable_serial_consent viene ignorato.

Nessun effetto per gli ID client OAuth più recenti, poiché per questi ultimi sono sempre attive autorizzazioni più granulari.
enable_serial_consent Deprecata. Devi usare enable_granular_consent. Ha lo stesso effetto di enable_granular_consent. Le applicazioni esistenti che utilizzano enable_serial_consent possono continuare a farlo, ma ti invitiamo ad aggiornare il tuo codice per utilizzare enable_granular_consent nel prossimo aggiornamento dell'applicazione.
login_hint Campo facoltativo. Se l'applicazione sa quale utente deve autorizzare la richiesta, può utilizzare questa proprietà per fornire un suggerimento di accesso a Google. Se l'operazione va a buon fine, la selezione dell'account viene saltata. Il valore del campo indirizzo email o token ID sub 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, usalo per fornire un suggerimento a Google. Se l'operazione va a buon fine, gli account utente vengono preselezionati o limitati per il dominio fornito. Per ulteriori informazioni, vedi il campo hd nella documentazione di OpenID Connect.
state Campo facoltativo. Non consigliati. Specifica qualsiasi valore 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, ad esempio la finestra popup non si apre o viene chiusa prima che venga restituita una risposta OAuth.

Il campo "type" 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.
  • sconosciuto Segnaposto per altri errori.

Tipo di dati: TokenClient

La classe ha un solo metodo pubblico requestAccessToken, che avvia il flusso UX del token OAuth 2.0.

interface TokenClient {
  requestAccessToken(overrideConfig?: OverridableTokenClientConfig): void;
}
Argomenti
overrideConfig OverridableTokenClientConfig Campo facoltativo. Le configurazioni da eseguire l'override in questo metodo.

Tipo di dati: OverridableTokenClientConfig

La seguente tabella 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 l'applicazione potrebbe accedere per conto dell'utente. Questi valori indicano la schermata di 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 approvata, il nuovo token di accesso coprirà solo gli ambiti a cui scope ha richiesto in questo OverridableTokenClientConfig.
prompt Campo facoltativo. Un elenco di prompt, delimitati da spazi e maiuscole, da presentare all'utente.
enable_granular_consent (Facoltativo) Il valore predefinito è true. Se impostato su false, le autorizzazioni più granulari dell'Account Google verrebbero disattivate per gli ID client OAuth creati prima del 2019.Se sono impostati entrambi enable_granular_consent e enable_serial_consent, verrà applicato solo il valore enable_granular_consent, mentre il valore enable_serial_consent verrà ignorato.

Nessun effetto per gli ID client OAuth più recenti, poiché per questi ultimi sono sempre attive autorizzazioni più granulari.
enable_serial_consent Deprecata. Devi usare enable_granular_consent. Ha lo stesso effetto di enable_granular_consent. Le applicazioni esistenti che utilizzano enable_serial_consent possono continuare a farlo, ma ti invitiamo ad aggiornare il tuo codice per utilizzare enable_granular_consent nel prossimo aggiornamento dell'applicazione.
login_hint Campo facoltativo. Se l'applicazione sa quale utente deve autorizzare la richiesta, può utilizzare questa proprietà per fornire un suggerimento di accesso a Google. Se l'operazione va a buon fine, la selezione dell'account viene saltata. Il valore del campo indirizzo email o token ID sub 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 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 tuo metodo di callback nell'UX popup.

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

Proprietà
access_token Il token di accesso di una risposta del 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 del prompt utilizzato dal possibile elenco di valori specificati da TokenClientConfig o OverridableTokenClientConfig.
token_type Il tipo di token emesso.
scope Un elenco delimitato da spazi di ambiti 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 che fornisce informazioni aggiuntive, utilizzato per aiutare lo sviluppatore del client a comprendere l'errore che si è verificato.
error_uri Un URI che identifica una pagina web leggibile con informazioni sull'errore, utilizzato 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 controllare.
restScopes stringa[] Campo facoltativo. Altri ambiti da verificare.
Ritorni
boolean True se tutti gli ambiti sono concessi.

Metodo: google.accounts.oauth2.hasGrantedAnyScope

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 controllare.
restScopes stringa[] Campo facoltativo. Altri ambiti da verificare.
Ritorni
boolean True se viene concesso uno o più ambiti.

Metodo: google.accounts.oauth2.revoke

Il metodo revoke revoca tutti gli ambiti concessi dall'utente 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 tuo metodo di callback.

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

Proprietà
successful Booleano. true in caso di errore, false in caso di errore.
error Stringa. Non definito per l'esito positivo. Un singolo codice di errore ASCII. inclusi, a titolo esemplificativo, i codici di errore standard OAuth 2.0. Errori comuni relativi al metodo revoke:
  • invalid_token: il token è già scaduto o revocato prima che venga chiamato il metodo revoke. Nella maggior parte dei casi, puoi considerare che la concessione associata a accessToken è stata revocata.
  • invalid_request - Il token non è revocabile. Devi assicurarti che accessToken sia una credenziale Google OAuth 2.0 valida.
error_description Stringa. Non definito per l'esito positivo. Il testo ASCII leggibile fornisce informazioni aggiuntive sulla proprietà error. Gli sviluppatori possono utilizzarlo per comprendere meglio l'errore che si è verificato. La stringa error_description è solo in inglese. Per gli errori comuni elencati in error il valore error_description corrispondente:
  • invalid_token: token scaduto o revocato.
  • invalid_request - Il token non è revocabile.