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

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Esta referência descreve a API da biblioteca de 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 é inicializado 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 do cliente do seu aplicativo. Você encontra esse valor 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.
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 do URI de redirecionamento. A propriedade será ignorada pela UX pop-up.
callback Obrigatório para UX pop-up. A função JavaScript que gerencia a resposta do código retornado. A propriedade será ignorada pela UX de redirecionamento.
state Opcional. Recomendado para UX de redirecionamento. Especifica qualquer valor de string que o 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 valor padrão é true. Se definido como false, as permissões mais granulares da Conta do Google serão desativadas para os clientes criados antes de 2019. Não há efeito para clientes mais novos, já que as permissões mais granulares estão sempre ativadas para eles.
hint Opcional. Se o aplicativo souber qual usuário deve autorizar a solicitação, ele poderá 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.
hosted_domain Opcional. Se o aplicativo souber o domínio do Google Workspace do usuário, use-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 para o fluxo de autorização. Por padrão, ele abre 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 que o usuário selecione uma conta.
error_callback Opcional. A função JavaScript que processa 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 não foi possível abrir a janela pop-up;
  • popup_closed A janela pop-up é fechada antes de uma resposta OAuth ser retornada.
  • Marcador desconhecido 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 do 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 delimitada por espaço de escopos aprovados pelo usuário.
state O valor da string que seu aplicativo usa para manter o estado entre sua solicitação de autorização e a resposta.
error Um único código de erro ASCII.
error_description Texto ASCII legível que fornece informações adicionais, usadas 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, usado para fornecer ao desenvolvedor cliente mais informações sobre o erro.

Método: google.accounts.oauth2.initTokenClient

O método initTokenClient é inicializado 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 do cliente do seu aplicativo. O valor está disponível no Console de APIs.
callback Obrigatório. A função JavaScript que gerencia 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.
prompt Opcional, o padrão é 'select_account'. Uma lista de solicitações delimitadas por espaço e diferencia maiúsculas de minúsculas para apresentar o usuário. Valores possíveis:
  • String vazia: o usuário receberá uma solicitação apenas na primeira vez que seu app solicitar acesso. Não pode ser especificado com outros valores.
  • 'none' não exibir telas de autenticação nem de consentimento. Não pode ser especificado com outros valores.
  • 'consent' Solicite o consentimento do usuário.
  • 'select_account' Instruir o usuário a selecionar uma conta.
enable_serial_consent Opcional: o valor padrão é true. Se definido como false, as permissões mais granulares da Conta do Google serão desativadas para os clientes criados antes de 2019. Não há efeito para clientes mais novos, já que as permissões mais granulares estão sempre ativadas para eles.
hint Opcional. Se o aplicativo souber qual usuário deve autorizar a solicitação, ele poderá 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.
hosted_domain Opcional. Se o aplicativo souber o domínio do Google Workspace do usuário, use-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 o 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 processa 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 não foi possível abrir a janela pop-up;
  • popup_closed A janela pop-up é fechada antes de uma resposta OAuth ser retornada.
  • Marcador desconhecido para outros erros.

Tipo de dados: TokenClient

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

interface TokenClient {
  requestAccessToken(overrideConfig?: OverridableTokenClientConfig): void;
}
Argumentos
overrideConfig OverridableTokenClientConfig. Opcional. As configurações que serão substituídas nesse método.

Tipo de dados: OverridableTokenClientConfig

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

Propriedades
prompt Opcional. Uma lista de solicitações delimitadas por espaços e com diferenciação entre maiúsculas e minúsculas para apresentar o usuário.
enable_serial_consent Opcional. Se definido como false, as permissões mais granulares da Conta do Google serão desativadas para os clientes criados antes de 2019. Não há efeito para clientes mais novos, já que as permissões mais granulares estão sempre ativadas para eles.
hint Opcional. Se o aplicativo souber qual usuário deve autorizar a solicitação, ele poderá 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 o aplicativo usa para manter o estado entre a solicitação de autorização e a resposta do servidor de autorização.

Tipo de dados: TokenResponse

Um objeto JavaScript TokenResponse será transmitido para seu 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 O ciclo de vida em segundos do token de acesso.
hd O domínio hospedado a que o usuário conectado pertence.
prompt O valor da solicitação que foi usado a partir da lista de valores possível especificada por TokenClientConfig ou OverridableTokenClientConfig.
token_type O tipo do token emitido.
scope É uma lista delimitada por espaço de escopos aprovados pelo usuário.
state O valor da string que seu aplicativo usa para manter o estado entre sua solicitação de autorização e a resposta.
error Um único código de erro ASCII.
error_description Texto ASCII legível que fornece informações adicionais, usadas 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, usado para fornecer ao desenvolvedor cliente mais informações 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 string Obrigatório. Um token de acesso válido.
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 dos escopos especificados.

google.accounts.oauth2.hasGrantedAnyScope(
                                           tokenResponse: TokenResponse,
                                           firstScope: string, ...restScopes: string[]
                                         ): boolean;
Argumentos
tokenResponse string Obrigatório. Um token de acesso válido.
firstScope string Obrigatório. O escopo a ser verificado.
restScopes string[] Opcional. Outros escopos a serem verificados.
Retorna
boolean Verdadeiro se algum 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 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.
done função Opcional. Função de callback depois que a ação de revogação é concluída.