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

Esta referência descreve a API Google 3P Authorization JavaScript Library, 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 do cliente do seu aplicativo. Esse valor está 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 outros escopos 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 vai abranger apenas os escopos para os quais o scope foi solicitado 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 do 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 do pop-up.
callback Obrigatório para a UX de pop-ups. A função JavaScript que lida com a resposta do código retornado. A propriedade será ignorada pela UX de redirecionamento.
state Opcional. Recomendado para a 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_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 detalhadas 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. Se for bem-sucedido, a seleção de conta será ignorada. O valor do campo sub do endereço de e-mail ou 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 ao qual o usuário pertence, use essa informação para dar uma dica ao Google. Quando bem-sucedido, 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 para o fluxo de autorização. Por padrão, ele vai 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 que o usuário selecione uma conta.
error_callback Opcional. A função JavaScript que processa alguns erros que não são do OAuth, como a janela pop-up não abrir ou fechar antes que uma resposta do OAuth seja retornada.

O campo "type" do parâmetro de entrada fornece o motivo detalhado.
  • popup_failed_to_open A janela pop-up não foi aberta.
  • 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 para o método callback na UX 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 e aprovada pelo usuário.
state O valor de string que o 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 por humanos 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 está no Console de APIs.
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 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 outros escopos 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 vai abranger apenas os escopos para os quais o scope foi solicitado neste TokenClientConfig.
prompt Opcional: o padrão é 'select_account'. Uma lista de solicitações delimitada por espaço, que diferencia maiúsculas de minúsculas, para apresentar ao usuário. Os valores possíveis são:
  • String vazia: o usuário vai receber uma solicitação apenas na primeira vez que o app solicitar 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' Peça o consentimento do usuário.
  • 'select_account' solicita que o usuário selecione uma conta.
enable_granular_consent Desativado, não tem efeito se definido. Consulte permissões detalhadas 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. Se for bem-sucedido, a seleção de conta será ignorada. O valor do campo sub do endereço de e-mail ou 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 ao qual o usuário pertence, use essa informação para dar uma dica ao Google. Quando bem-sucedido, 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 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 que não são do OAuth, como a janela pop-up não abrir ou fechar antes que uma resposta do OAuth seja retornada.

O campo "type" do parâmetro de entrada informa o motivo detalhado.
  • popup_failed_to_open A janela pop-up não foi aberta.
  • 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 de UX do token OAuth 2.0.

interface TokenClient {
  requestAccessToken(overrideConfig?: OverridableTokenClientConfig): void;
}
Argumentos
overrideConfig OverridableTokenClientConfig Opcional. As configurações que serão 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 o 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 outros escopos 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 vai abranger apenas os escopos para os quais o scope foi solicitado neste OverridableTokenClientConfig.
prompt Opcional. Uma lista de solicitações delimitada por espaços e que diferencia maiúsculas de minúsculas para apresentar ao usuário.
enable_granular_consent Desativado, não tem efeito se definido. Consulte permissões detalhadas para detalhes sobre o comportamento de consentimento.
enable_serial_consent Desativado, não tem efeito se definido. Consulte permissões detalhadas 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. Se for bem-sucedido, a seleção de conta será ignorada. O valor do campo sub do token de ID ou 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 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 do token de acesso em segundos.
hd O domínio hospedado ao qual o usuário conectado pertence.
prompt O valor da solicitação que foi usado da lista possível de valores especificados por TokenClientConfig ou OverridableTokenClientConfig.
token_type O tipo de token emitido.
scope Uma lista de escopos delimitada por espaço e aprovada pelo usuário.
state O valor de string que o 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 por humanos 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 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 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. Um token de acesso válido é necessário 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. Handler de 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 para sucesso, false para 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 é revogável. 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 por humanos 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, o error_description correspondente:
  • invalid_token: o token expirou ou foi revogado.
  • invalid_request: o token não é revogável.