Referência da API JavaScript de autorização de Conta do Google

Esta referência descreve a API JavaScript de autorização da Conta do Google, usada para receber 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 do cliente do seu 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 mostra ao usuário.
include_granted_scopes Opcional, o padrão é true. Permite que os aplicativos usem a autorização incremental para solicitar acesso a escopos adicionais no contexto. Se você definir o valor desse parâmetro como false e o pedido de autorização for concedido, o novo token de acesso vai abranger apenas os escopos que o scope solicitou neste CodeClientConfig.
redirect_uri Obrigatório para a UX de redirecionamento. Determina para onde o servidor da 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 de acordo com nossas regras de validação de URI de redirecionamento. A propriedade será ignorada pela UX do pop-up.
callback Obrigatório para a UX de pop-up. A função JavaScript que processa 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 seu aplicativo usa para manter o estado entre a solicitação de autorização e a resposta do servidor de autorização.
enable_granular_consent Desativado, não tem efeito se definido. Consulte permissões granulares para detalhes sobre o comportamento de consentimento.
enable_serial_consent Desativado, não tem efeito se definido. Consulte permissões granulares para detalhes sobre o comportamento de consentimento.
login_hint Opcional. Se o aplicativo souber qual usuário deve autorizar a solicitação, ele poderá usar essa propriedade para fornecer uma dica de login ao Google. Quando a operação é bem-sucedida, a seleção de contas é ignorada. O endereço de e-mail ou o valor do campo sub do token de ID para o usuário de destino. Para mais informações, consulte o campo login_hint na documentação do OpenID Connect.
hd Opcional. Se o aplicativo souber o domínio do Workspace a que o usuário pertence, use isso para dar uma dica ao Google. Quando bem-sucedidas, as contas de usuário são limitadas ou pré-selecionadas para o domínio fornecido. 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 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 pedir ao usuário que selecione uma conta.
error_callback Opcional. A função JavaScript que processa alguns erros não relacionados ao OAuth, como falha ao abrir a janela pop-up ou fechamento antes do retorno de uma resposta do OAuth.

O campo "type" do parâmetro de entrada informa 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 que uma resposta do OAuth seja retornada.
  • unknown: marcador de posição 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 ao método callback na experiência do usuário do 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 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 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 por humanos com informações sobre o erro, usado para fornecer ao desenvolvedor do cliente mais informações 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 do cliente do seu aplicativo. Esse valor pode ser encontrado no Console de APIs.
callback Obrigatório. A função JavaScript que processa 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 mostra ao usuário.
include_granted_scopes Opcional, o padrão é true. Permite que os aplicativos usem a autorização incremental para solicitar acesso a escopos adicionais no contexto. Se você definir o valor desse parâmetro como false e o pedido de autorização for concedido, o novo token de acesso vai abranger apenas os escopos que o scope solicitou neste TokenClientConfig.
prompt Opcional, o padrão é 'select_account'. Uma lista de comandos delimitada por espaço e sensível a maiúsculas e minúsculas para apresentar ao usuário. Os valores possíveis são:
  • string vazia: o usuário vai receber a solicitação apenas na primeira vez que o app pedir acesso. Não pode ser especificado com outros valores.
  • "none": não mostra nenhuma tela de autenticação ou consentimento. Não pode ser especificado com outros valores.
  • consent: pede o consentimento do usuário.
  • 'select_account': pede que o usuário selecione uma conta.
enable_granular_consent Desativado, não tem efeito se definido. Consulte permissões granulares para detalhes sobre o comportamento de consentimento.
enable_serial_consent Desativado, não tem efeito se definido. Consulte permissões granulares para detalhes sobre o comportamento de consentimento.
login_hint Opcional. Se o aplicativo souber qual usuário deve autorizar a solicitação, ele poderá usar essa propriedade para fornecer uma dica de login ao Google. Quando a operação é bem-sucedida, a seleção de contas é ignorada. O endereço de e-mail ou o valor do campo sub do token de ID para o usuário de destino. Para mais informações, consulte o campo login_hint na documentação do OpenID Connect.
hd Opcional. Se o aplicativo souber o domínio do Workspace a que o usuário pertence, use isso para dar uma dica ao Google. Quando bem-sucedidas, as contas de usuário são limitadas ou pré-selecionadas para o domínio fornecido. 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 processa alguns erros não relacionados ao OAuth, como falha ao abrir a janela pop-up ou fechamento antes do retorno de uma resposta do OAuth.

O campo "type" do parâmetro de entrada informa 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 que uma resposta do OAuth seja retornada.
  • unknown: marcador de posição para outros erros.

Tipo de dados: TokenClient

A classe tem apenas um método público requestAccessToken, que inicia o fluxo da experiência do usuário do token OAuth 2.0.

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

Tipo de dados: OverridableTokenClientConfig

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

Propriedades
scope Opcional. Uma lista delimitada por espaço de escopos que identificam os recursos que seu aplicativo pode acessar em nome do usuário. Esses valores informam a tela de consentimento que o Google mostra ao usuário.
include_granted_scopes Opcional, o padrão é true. Permite que os aplicativos usem a autorização incremental para solicitar acesso a escopos adicionais no contexto. Se você definir o valor desse parâmetro como false e o pedido de autorização for concedido, o novo token de acesso vai abranger apenas os escopos que o scope solicitou neste OverridableTokenClientConfig.
prompt Opcional. Uma lista de solicitações delimitada por espaço e sensível a maiúsculas e minúsculas para apresentar ao usuário.
enable_granular_consent Desativado, não tem efeito se definido. Consulte permissões granulares para detalhes sobre o comportamento de consentimento.
enable_serial_consent Desativado, não tem efeito se definido. Consulte permissões granulares para detalhes sobre o comportamento de consentimento.
login_hint Opcional. Se o aplicativo souber qual usuário deve autorizar a solicitação, ele poderá usar essa propriedade para fornecer uma dica de login ao Google. Quando a operação é bem-sucedida, a seleção de contas é ignorada. O endereço de e-mail ou o valor do campo sub do token de ID para o 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 dados: TokenResponse

Um objeto JavaScript TokenResponse será transmitido ao método de callback na UX do 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 de solicitação que foi usado na lista de valores possíveis especificados por TokenClientConfig ou OverridableTokenClientConfig.
token_type O tipo de token emitido.
scope Uma lista de escopos delimitada por espaço 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 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 por humanos com informações sobre o erro, usado para fornecer ao desenvolvedor do 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 TokenResponse Obrigatório. Um objeto TokenResponse.
firstScope string Obrigatório. O escopo a ser verificado.
restScopes string[] Opcional. Outros escopos a serem verificados.
Retorna
booleano True 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 TokenResponse Obrigatório. Um objeto TokenResponse.
firstScope string Obrigatório. O escopo a ser verificado.
restScopes string[] Opcional. Outros escopos a serem verificados.
Retorna
booleano Verdadeiro se algum dos escopos for concedido.

Método: google.accounts.oauth2.revoke

O método revoke revoga todos os escopos que o usuário concedeu 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.
callback função Opcional. Processador RevocationResponse.

Tipo de dados: RevocationResponse

Um objeto JavaScript RevocationResponse será transmitido ao seu método de callback.

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

Propriedades
successful Booleano. true em caso de sucesso e false em caso de falha.
error String. Indefinido em caso de sucesso. Um único código de erro ASCII. Isso inclui, mas não se limita aos códigos de erro padrão do OAuth 2.0. Erros comuns para o método revoke:
  • invalid_token: o token já expirou ou foi revogado antes da chamada do método revoke. Na maioria dos casos, a concessão associada ao accessToken é 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. Indefinido em caso de sucesso. O texto ASCII legível fornece mais informações sobre a propriedade error. Os desenvolvedores podem usar isso para entender melhor o erro que ocorreu. A string error_description está disponível apenas em inglês. Para os erros comuns listados em error, confira o error_description correspondente:
  • invalid_token: o token expirou ou foi revogado.
  • invalid_request: o token não pode ser revogado.