Biblioteca JavaScript da autorização de terceiros do Google para sites - referência da API

Esta referência descreve a API da biblioteca JavaScript de autorização de terceiros do Google, que pode ser usada para carregar códigos de autorização ou tokens de acesso do Google.

Método: google.accounts.oauth2.initCodeClient

O método initCodeClient inicializa e retorna um cliente de código, com as configurações no parâmetro.

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

Tipo de dados: CodeClientConfig

A tabela a seguir lista as propriedades do tipo de dados CodeClientConfig.

Propriedades
client_id Obrigatório. O ID de cliente do aplicativo. Esse valor pode ser encontrado no Console de APIs.
scope Obrigatório. A lista de escopos delimitada por espaços que identificam os recursos que seu aplicativo pode acessar em nome do usuário. Esses valores informam a tela de consentimento que o Google exibe ao usuário.
include_granted_scopes Opcional: o padrão é true. Permite que os aplicativos usem autorização incremental para solicitar acesso a escopos adicionais no contexto. Se você definir o valor desse parâmetro como false e a solicitação de autorização for concedida, o novo token de acesso cobrirá apenas os escopos solicitados pelo scope neste CodeClientConfig.
redirect_uri Obrigatório para UX de redirecionamento. Determina para onde o servidor de API redireciona o usuário depois que ele conclui o fluxo de autorização. O valor precisa corresponder exatamente a um dos URIs de redirecionamento autorizados para o cliente OAuth 2.0, que você configurou no Console de APIs e precisa estar em conformidade com nossas regras de validação de URI de redirecionamento. A propriedade será ignorada pela UX pop-up.
callback Obrigatório para UX de pop-up. A função JavaScript que lida com a resposta de código retornada. A propriedade será ignorada pela UX de redirecionamento.
state Opcional. Recomendado para UX de redirecionamento. Especifica qualquer valor de string que seu aplicativo usa para manter o estado entre a solicitação de autorização e a resposta do servidor de autorização.
enable_serial_consent Opcional: o padrão é true. Se ele for definido como false, as permissões mais detalhadas da Conta do Google serão desativadas para os IDs do cliente OAuth criados antes de 2019. Nenhum efeito para IDs do cliente OAuth mais recentes, já que permissões mais granulares estão sempre ativadas para eles.
hint Opcional. Se seu aplicativo sabe qual usuário deve autorizar a solicitação, ele pode usar essa propriedade para fornecer uma dica ao Google. O endereço de e-mail do usuário de destino. Para mais informações, consulte o campo login_hint na documentação do OpenID Connect.
hd Opcional. Se o aplicativo sabe o domínio do Workspace a que o usuário pertence, use essa informação para dar uma dica ao Google. Para mais informações, consulte o campo hd na documentação do OpenID Connect.
ux_mode Opcional. O modo de UX a ser usado no fluxo de autorização. Por padrão, ele abrirá o fluxo de consentimento em um pop-up. Os valores válidos são: popup e redirect.
select_account Opcional: o padrão é 'false'. Valor booleano para solicitar ao usuário para selecionar uma conta.
error_callback Opcional. A função JavaScript que lida com alguns erros não OAuth, como a janela pop-up, não é aberta ou fechada antes que uma resposta OAuth seja retornada.

O campo "type" do parâmetro de entrada fornece o motivo detalhado.
  • popup_failed_to_open falha ao abrir a janela pop-up;
  • popup_closed A janela pop-up é fechada antes que uma resposta OAuth seja retornada.
  • unknown para outros erros.

Tipo de dados: CodeClient

A classe tem apenas um método público requestCode, que inicia o fluxo de UX do código OAuth 2.0.

interface CodeClient {
  requestCode(): void;
}

Tipo de dados: CodeResponse

Um objeto JavaScript CodeResponse será transmitido para o método callback na UX pop-up. Na UX de redirecionamento, o CodeResponse será transmitido como parâmetros de URL.

A tabela a seguir lista as propriedades do tipo de dados CodeResponse.

Propriedades
code O código de autorização de uma resposta de token bem-sucedida.
scope Uma lista de escopos delimitada por espaço que é aprovada pelo usuário.
state O valor da string que seu aplicativo usa para manter o estado entre a solicitação de autorização e a resposta.
error Um único código de erro ASCII.
error_description Texto legível que fornece informações adicionais, usado para ajudar o desenvolvedor do cliente a entender o erro que ocorreu.
error_uri Um URI que identifica uma página da web legível com informações sobre o erro, usada para fornecer ao desenvolvedor cliente informações adicionais sobre o erro.

Método: google.accounts.oauth2.initTokenClient

O método initTokenClient inicializa e retorna um cliente de token, com as configurações no parâmetro.

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

Tipo de dados: TokenClientConfig

A tabela a seguir lista as propriedades do tipo de dados TokenClientConfig.

Propriedades
client_id Obrigatório. O ID de cliente do aplicativo. É possível encontrar esse valor no Console de API.
callback Obrigatório. A função JavaScript que lida com a resposta do token retornado.
scope Obrigatório. A lista de escopos delimitada por espaços que identificam os recursos que seu aplicativo pode acessar em nome do usuário. Esses valores informam a tela de consentimento que o Google exibe ao usuário.
include_granted_scopes Opcional: o padrão é true. Permite que os aplicativos usem autorização incremental para solicitar acesso a escopos adicionais no contexto. Se você definir o valor desse parâmetro como false e a solicitação de autorização for concedida, o novo token de acesso cobrirá apenas os escopos solicitados pelo scope neste TokenClientConfig.
prompt Opcional: o padrão é 'select_account'. Uma lista de solicitações delimitadas por espaços, que diferenciam maiúsculas de minúsculas, para apresentar ao usuário. Os valores possíveis são:
  • string vazia: o usuário receberá uma solicitação apenas na primeira vez que o app solicitar acesso. Não pode ser especificado com outros valores.
  • "none" não exibe nenhuma tela de autenticação ou consentimento. Não pode ser especificado com outros valores.
  • 'consent': solicita o consentimento do usuário.
  • 'select_account': solicitar que o usuário selecione uma conta
enable_serial_consent Opcional: o padrão é true. Se ele for definido como false, as permissões mais detalhadas da Conta do Google serão desativadas para os IDs do cliente OAuth criados antes de 2019. Nenhum efeito para IDs do cliente OAuth mais recentes, já que permissões mais granulares estão sempre ativadas para eles.
hint Opcional. Se seu aplicativo sabe qual usuário deve autorizar a solicitação, ele pode usar essa propriedade para fornecer uma dica ao Google. O endereço de e-mail do usuário de destino. Para mais informações, consulte o campo login_hint na documentação do OpenID Connect.
hd Opcional. Se o aplicativo sabe o domínio do Workspace a que o usuário pertence, use essa informação para dar uma dica ao Google. Para mais informações, consulte o campo hd na documentação do OpenID Connect.
state Opcional. Não recomendado. Especifica qualquer valor de string que seu aplicativo usa para manter o estado entre a solicitação de autorização e a resposta do servidor de autorização.
error_callback Opcional. A função JavaScript que lida com alguns erros não OAuth, como a janela pop-up, não é aberta ou fechada antes que uma resposta OAuth seja retornada.

O campo "type" do parâmetro de entrada fornece o motivo detalhado.
  • popup_failed_to_open falha ao abrir a janela pop-up;
  • popup_closed A janela pop-up é fechada antes que uma resposta OAuth seja retornada.
  • unknown para outros erros.

Tipo de dado: TokenClient

A classe tem apenas um método público requestAccessToken, que inicia o fluxo de UX do token OAuth 2.0.

interface TokenClient {
  requestAccessToken(overrideConfig?: OverridableTokenClientConfig): void;
}
Argumentos
overrideConfig OverridableTokenClientConfig. Opcional. As configurações a serem modificadas neste método.

Tipo de dados: OverridableTokenClientConfig

A tabela a seguir lista as propriedades do tipo de dados OverridableTokenClientConfig.

Propriedades
scope Opcional. Uma lista de escopos delimitada por espaços que identifica os recursos que seu aplicativo pode acessar em nome do usuário. Esses valores informam a tela de consentimento que o Google exibe ao usuário.
include_granted_scopes Opcional: o padrão é true. Permite que os aplicativos usem autorização incremental para solicitar acesso a escopos adicionais no contexto. Se você definir o valor desse parâmetro como false e a solicitação de autorização for concedida, o novo token de acesso cobrirá apenas os escopos solicitados pelo scope neste OverridableTokenClientConfig.
prompt Opcional. Uma lista de solicitações delimitadas por espaços e que diferenciam maiúsculas de minúsculas para apresentar ao usuário.
enable_serial_consent Opcional: o padrão é true. Se ele for definido como false, as permissões mais detalhadas da Conta do Google serão desativadas para os IDs do cliente OAuth criados antes de 2019. Nenhum efeito para IDs do cliente OAuth mais recentes, já que permissões mais granulares estão sempre ativadas para eles.
hint Opcional. Se seu aplicativo sabe qual usuário deve autorizar a solicitação, ele pode usar essa propriedade para fornecer uma dica ao Google. O endereço de e-mail do usuário de destino. Para mais informações, consulte o campo login_hint na documentação do OpenID Connect.
state Opcional. Não recomendado. Especifica qualquer valor de string que seu aplicativo usa para manter o estado entre a solicitação de autorização e a resposta do servidor de autorização.

Tipo de dado: TokenResponse

Um objeto JavaScript TokenResponse será transmitido para o método de callback na UX pop-up.

A tabela a seguir lista as propriedades do tipo de dados TokenResponse.

Propriedades
access_token O token de acesso de uma resposta de token bem-sucedida.
expires_in A vida útil em segundos do token de acesso.
hd O domínio hospedado ao qual o usuário conectado pertence.
prompt O valor da solicitação usado a partir da lista de valores possíveis especificada por TokenClientConfig ou OverridableTokenClientConfig.
token_type O tipo do token emitido.
scope Uma lista de escopos delimitada por espaço que é aprovada pelo usuário.
state O valor da string que seu aplicativo usa para manter o estado entre a solicitação de autorização e a resposta.
error Um único código de erro ASCII.
error_description Texto ASCII legível com informações adicionais, usado para ajudar o desenvolvedor do cliente a entender o erro que ocorreu.
error_uri Um URI que identifica uma página da web legível com informações sobre o erro, usada para fornecer ao desenvolvedor cliente informações adicionais sobre o erro.

Método: google.accounts.oauth2.hasGrantedAllScopes

Verifica se o usuário concedeu todos os escopos especificados.

google.accounts.oauth2.hasGrantedAllScopes(
                                            tokenResponse: TokenResponse,
                                            firstScope: string, ...restScopes: string[]
                                          ): boolean;
Argumentos
tokenResponse TokenResponse Obrigatório. Um objeto TokenResponse.
firstScope string Obrigatório. O escopo a ser verificado.
restScopes string[] Opcional. Outros escopos a serem verificados.
Retorna
boolean Verdadeiro se todos os escopos forem concedidos.

Método: google.accounts.oauth2.hasGrantedAnyScope

Verifica se o usuário concedeu algum ou mais escopos especificados.

google.accounts.oauth2.hasGrantedAnyScope(
                                           tokenResponse: TokenResponse,
                                           firstScope: string, ...restScopes: string[]
                                         ): boolean;
Argumentos
tokenResponse TokenResponse Obrigatório. Um objeto TokenResponse.
firstScope string Obrigatório. O escopo a ser verificado.
restScopes string[] Opcional. Outros escopos a serem verificados.
Retorna
boolean Verdadeiro se qualquer um dos escopos for concedido.

Método: google.accounts.oauth2.revoke

O método revoke revoga todos os escopos concedidos pelo usuário ao app. É necessário ter um token de acesso válido para revogar a permissão.

google.accounts.oauth2.revoke(accessToken: string, done: () => void): void;
Argumentos
accessToken string Obrigatório. Um token de acesso válido.
callback função Opcional. RevocationResponse.

Tipo de dados: RevocationResponse

Um objeto JavaScript RevocationResponse será transmitido para o método de callback.

A tabela a seguir lista as propriedades do tipo de dados RevocationResponse.

Propriedades
successful Booleano. true com êxito, false com falha.
error String. Indefinida no sucesso. Um único código de erro ASCII. Isso inclui, sem limitação, os códigos de erro padrão do OAuth 2.0. Erros comuns do método revoke:
  • invalid_token: o token já expirou ou foi revogado antes de chamar o método revoke. Na maioria dos casos, a concessão associada ao accessToken pode ser revogada.
  • invalid_request: o token não pode ser revogado. Verifique se accessToken é uma credencial válida do Google OAuth 2.0.
error_description String. Indefinida no sucesso. O texto ASCII legível fornece informações adicionais sobre a propriedade error. Os desenvolvedores podem usar isso para entender melhor o erro que ocorreu. A string error_description está apenas em inglês. Para os erros comuns listados em error, o error_description correspondente:
  • invalid_token: token expirado ou revogado.
  • invalid_request: o token não pode ser revogado.