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

Questa pagina di riferimento descrive l'API Google 3rd Party Authorization JavaScript Library, che puoi utilizzare per caricare codici di autorizzazione o token di accesso 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. Puoi trovare questo valore nella console API.
scope Obbligatorio. Un elenco di ambiti separati da spazi che identificano le risorse a cui la tua applicazione potrebbe accedere per conto dell'utente. Questi valori vengono utilizzati nella schermata di consenso mostrata da Google 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 a cui è stato richiesto scope in questo CodeClientConfig.
redirect_uri Obbligatorio per l'esperienza utente di reindirizzamento. Determina dove il server API reindirizza l'utente dopo che 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 API e deve essere conforme alle nostre regole di convalida degli URI di reindirizzamento. La proprietà verrà ignorata dall'esperienza utente popup.
callback Obbligatorio per l'esperienza utente popup. La funzione JavaScript che gestisce la risposta del codice restituito. La proprietà verrà ignorata dall'esperienza utente di reindirizzamento.
state (Facoltativo) Consigliato per l'esperienza utente del 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_granular_consent Ritirato, non ha alcun effetto se impostato. Per informazioni dettagliate sul comportamento del consenso, consulta la sezione relativa alle autorizzazioni granulari.
enable_serial_consent Ritirato, non ha alcun effetto se impostato. Per informazioni dettagliate sul comportamento del consenso, consulta la sezione relativa alle autorizzazioni granulari.
login_hint (Facoltativo) Se la tua applicazione sa quale utente deve autorizzare la richiesta, può utilizzare questa proprietà per fornire un suggerimento per l'accesso a Google. In caso di esito positivo, la selezione dell'account viene ignorata. Il valore del campo sub dell'indirizzo email o del token ID per l'utente di destinazione. Per ulteriori informazioni, consulta il campo login_hint nella documentazione di OpenID Connect.
hd (Facoltativo) Se la tua applicazione conosce il dominio Workspace a cui appartiene l'utente, utilizzalo per fornire un suggerimento a Google. In caso di esito positivo, gli account utente sono limitati o preselezionati per il dominio fornito. Per ulteriori informazioni, consulta il campo hd nella documentazione di OpenID Connect.
ux_mode (Facoltativo) La modalità UX da utilizzare per il flusso di autorizzazione. Per impostazione predefinita, il flusso di consenso si aprirà in un popup. I valori validi sono popup e redirect.
select_account Facoltativo, il valore predefinito è 'false'. Valore booleano per chiedere all'utente di selezionare un account.
error_callback (Facoltativo) La funzione JavaScript che gestisce alcuni errori non OAuth, ad esempio la mancata apertura della finestra popup o la chiusura prima della restituzione di 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.
  • unknown Segnaposto per altri errori.

Tipo di dati: CodeClient

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

interface CodeClient {
  requestCode(): void;
}

Tipo di dati: CodeResponse

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

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

Proprietà
code Il codice di autorizzazione di una risposta del token positiva.
scope Un elenco delimitato da spazi di ambiti approvati dall'utente.
state Il valore di stringa utilizzato dall'applicazione 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 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 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. Puoi trovare questo valore nella console API.
callback Obbligatorio. La funzione JavaScript che gestisce la risposta del token restituito.
scope Obbligatorio. Un elenco di ambiti separati da spazi che identificano le risorse a cui la tua applicazione potrebbe accedere per conto dell'utente. Questi valori vengono utilizzati nella schermata di consenso mostrata da Google 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 a cui è stato richiesto scope in questo TokenClientConfig.
prompt Facoltativo, il valore predefinito è 'select_account'. Un elenco di prompt da presentare all'utente, distinto da spazi e sensibile alle maiuscole. I valori possibili sono:
  • stringa vuota All'utente verrà chiesto di confermare solo la prima volta che la tua app richiede l'accesso. Non può essere specificato con altri valori.
  • 'none' Non mostrare schermate di autenticazione o consenso. Non deve essere specificato con altri valori.
  • 'consent' Chiedi all'utente il consenso.
  • 'select_account' Chiedi all'utente di selezionare un account.
enable_granular_consent Ritirato, non ha alcun effetto se impostato. Per informazioni dettagliate sul comportamento del consenso, consulta la sezione relativa alle autorizzazioni granulari.
enable_serial_consent Ritirato, non ha alcun effetto se impostato. Per informazioni dettagliate sul comportamento del consenso, consulta la sezione relativa alle autorizzazioni granulari.
login_hint (Facoltativo) Se la tua applicazione sa quale utente deve autorizzare la richiesta, può utilizzare questa proprietà per fornire un suggerimento per l'accesso a Google. In caso di esito positivo, la selezione dell'account viene ignorata. Il valore del campo sub dell'indirizzo email o del token ID per l'utente di destinazione. Per ulteriori informazioni, consulta il campo login_hint nella documentazione di OpenID Connect.
hd (Facoltativo) Se la tua applicazione conosce il dominio Workspace a cui appartiene l'utente, utilizzalo per fornire un suggerimento a Google. In caso di esito positivo, gli account utente sono limitati o preselezionati per il dominio fornito. Per ulteriori informazioni, consulta il campo hd nella documentazione di OpenID Connect.
state (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 (Facoltativo) La funzione JavaScript che gestisce alcuni errori non OAuth, ad esempio la mancata apertura della finestra popup o la chiusura prima della restituzione di 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.
  • unknown 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 (Facoltativo) Le configurazioni da eseguire in override in questo metodo.

Tipo di dati: OverridableTokenClientConfig

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

Proprietà
scope (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 informano 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 concessa, il nuovo token di accesso coprirà solo gli ambiti a cui è stato richiesto scope in questo OverridableTokenClientConfig.
prompt (Facoltativo) Un elenco di prompt da presentare all'utente, separati da spazi e sensibili alle maiuscole.
enable_granular_consent Ritirato, non ha alcun effetto se impostato. Per informazioni dettagliate sul comportamento del consenso, consulta la sezione relativa alle autorizzazioni granulari.
enable_serial_consent Ritirato, non ha alcun effetto se impostato. Per informazioni dettagliate sul comportamento del consenso, consulta la sezione relativa alle autorizzazioni granulari.
login_hint (Facoltativo) Se la tua applicazione sa quale utente deve autorizzare la richiesta, può utilizzare questa proprietà per fornire un suggerimento per l'accesso a Google. In caso di esito positivo, la selezione dell'account viene ignorata. Il valore del campo sub dell'indirizzo email o del token ID per l'utente di destinazione. Per ulteriori informazioni, consulta il campo login_hint nella documentazione di OpenID Connect.
state (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 del popup.

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

Proprietà
access_token Il token di accesso di una risposta del token corretta.
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 della richiesta utilizzato dall'elenco di possibili 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 di stringa utilizzato dall'applicazione 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 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 client informazioni aggiuntive sull'errore.

Metodo: google.accounts.oauth2.hasGrantedAllScopes

Controlla 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[] (Facoltativo) Altri ambiti da controllare.
Resi
booleano True se tutti gli ambiti sono concessi.

Metodo: google.accounts.oauth2.hasGrantedAnyScope

Controlla se l'utente ha concesso uno o più degli 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[] (Facoltativo) Altri ambiti da controllare.
Resi
booleano True se uno degli ambiti è concesso.

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 (Facoltativo) Handler 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 in caso di successo, false in caso di errore.
error Stringa. Undefined in caso di esito positivo. 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 al metodo revoke. Nella maggior parte dei casi, puoi considerare che la concessione associata al accessToken è revocata.
  • invalid_request: il token non è revocabile. Assicurati che accessToken sia una credenziale Google OAuth 2.0 valida.
error_description Stringa. Undefined in caso di 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 è disponibile solo in inglese. Per gli errori comuni elencati in error, il error_description corrispondente:
  • invalid_token: token scaduto o revocato.
  • invalid_request: il token non è revocabile.