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

Esta referência descreve a API 3P Authorization JavaScript Library do Google, que pode ser usado 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 a de configuração 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 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 autorização 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 é concedida, o novo token de acesso vai abranger apenas os escopos solicitados por scope nesta CodeClientConfig.
redirect_uri Obrigatório para 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 deve corresponder exatamente a um dos URIs de redirecionamento autorizados para o cliente OAuth 2.0, que você configurou no Console de APIs, e deve seguir 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 lida com 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 Opcional, o padrão é true. Se definido como false, permissões da Conta do Google mais granulares seria desativado para IDs do cliente OAuth criados antes de 2019. Se enable_granular_consent e enable_serial_consent forem definidos, apenas enable_granular_consent valor entraria em vigor, e o valor enable_serial_consent seria ignorado.

Nenhum efeito para IDs de cliente OAuth mais recentes, já que permissões mais granulares estão sempre ativadas para eles.
enable_serial_consent Obsoleto. Use enable_granular_consent. Isso tem o mesmo efeito que enable_granular_consent. Aplicativos atuais que usam enable_serial_consent podem continuar a fazer isso, mas você está a atualizar seu código para usar enable_granular_consent em na próxima atualização do seu aplicativo.
login_hint Opcional. Se o seu aplicativo souber qual usuário deve autorizar a solicitação, ele poderá usar essa propriedade para fornecer uma dica de login ao Google. Após a conclusão, a seleção da conta é ignorada. O valor do campo sub do endereço de e-mail ou 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 essa informação para dar uma dica ao Google. Quando bem-sucedidos, 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 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 solicitar que o usuário selecione uma conta.
error_callback Opcional. A função JavaScript que lida com alguns erros não OAuth, como o não foi possível abrir a janela pop-up. ou fechado antes que uma resposta OAuth seja retornados.

O campo "type" do parâmetro de entrada informa o motivo detalhado.
  • popup_failed_to_open: falha ao abrir a janela pop-up.
  • popup_closed A janela pop-up é fechada antes de uma solicitação de OAuth será retornada.
  • unknown Marcador de posição para outros erros.

Tipo de dados: CodeClient

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

interface CodeClient {
  requestCode(): void;
}

Tipo de dados: CodeResponse

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

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 aprovados pelo usuário delimitada por espaços.
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 fornecendo informações adicionais, usado para ajudar o desenvolvedor do cliente a entender o erro ocorrido.
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 a de configuração 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 aplicativo. Você pode encontrar esse valor 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 autorização 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 é concedida, o novo token de acesso vai abranger apenas os escopos solicitados por scope nesta TokenClientConfig.
prompt Opcional. O padrão é 'select_account'. Uma string delimitada por espaço, lista de prompts para apresentar ao usuário, com diferenciação entre maiúsculas e minúsculas. Os valores possíveis são:
  • 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 mostra telas de autenticação ou consentimento. Não pode ser especificado com outros valores.
  • 'consent': pede o consentimento do usuário.
  • 'select_account': solicita que o usuário selecione uma conta.
enable_granular_consent Opcional, o padrão é true. Se definido como false, permissões da Conta do Google mais granulares seria desativado para IDs do cliente OAuth criados antes de 2019. Se enable_granular_consent e enable_serial_consent forem definidos, apenas enable_granular_consent valor entraria em vigor, e o valor enable_serial_consent seria ignorado.

Nenhum efeito para IDs de cliente OAuth mais recentes, já que permissões mais granulares estão sempre ativadas para eles.
enable_serial_consent Obsoleto. Use enable_granular_consent. Isso tem o mesmo efeito que enable_granular_consent. Aplicativos atuais que usam enable_serial_consent podem continuar a fazer isso, mas você está a atualizar seu código para usar enable_granular_consent em na próxima atualização do seu aplicativo.
login_hint Opcional. Se o seu aplicativo souber qual usuário deve autorizar a solicitação, ele poderá usar essa propriedade para fornecer uma dica de login ao Google. Após a conclusão, a seleção da conta é ignorada. O valor do campo sub do endereço de e-mail ou 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 essa informação para dar uma dica ao Google. Quando bem-sucedidos, 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 lida com alguns erros não OAuth, como o não foi possível abrir a janela pop-up. ou fechado antes que uma resposta OAuth seja retornados.

O campo "type" do parâmetro de entrada informa o motivo detalhado.
  • popup_failed_to_open: falha ao abrir a janela pop-up.
  • popup_closed A janela pop-up é fechada antes de uma solicitação de OAuth será 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 a serem substituídas neste método.

Tipo de dados: OverridableTokenClientConfig

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

Propriedades
scope Opcional. Uma 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 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 é concedida, o novo token de acesso vai abranger apenas os escopos solicitados por scope nesta OverridableTokenClientConfig.
prompt Opcional. Uma lista de comandos para apresentar ao usuário, delimitada por espaços e que diferencia maiúsculas de minúsculas.
enable_granular_consent Opcional, o padrão é true. Se definido como false, permissões da Conta do Google mais granulares seria desativado para IDs do cliente OAuth criados antes de 2019.Se enable_granular_consent e enable_serial_consent forem definidos, apenas enable_granular_consent valor entraria em vigor e o valor enable_serial_consent seria ignorado.

Nenhum efeito para IDs de cliente OAuth mais recentes, já que permissões mais granulares estão sempre ativadas para eles.
enable_serial_consent Obsoleto. Use enable_granular_consent. Isso tem o mesmo efeito que enable_granular_consent. Aplicativos atuais que usam enable_serial_consent podem continuar a fazer isso, mas você está a atualizar seu código para usar enable_granular_consent em na próxima atualização do seu aplicativo.
login_hint Opcional. Se o seu aplicativo souber qual usuário deve autorizar a solicitação, ele poderá usar essa propriedade para fornecer uma dica de login ao Google. Após a conclusão, a seleção da conta é ignorada. O valor do campo sub do endereço de e-mail ou 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 para o método de callback em a 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 Ciclo de vida em segundos do token de acesso.
hd O domínio hospedado a que o usuário que fez login pertence.
prompt O valor da solicitação que foi usado na lista de valores especificados por TokenClientConfig ou OverridableTokenClientConfig.
token_type O tipo de token emitido.
scope Uma lista de escopos aprovados pelo usuário delimitada por espaços.
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 fornecendo 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. Uma TokenResponse objeto.
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. Uma TokenResponse objeto.
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 concedidos pelo usuário 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. 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 em caso de êxito, false em caso de falha.
error String. Indefinida em caso de sucesso. Um único código de erro ASCII. Isso inclui, sem limitação, os requisitos padrão Códigos de erro 2.0. Erros comuns para o método revoke:
  • invalid_token: o token já expirou ou foi revogado antes que o método revoke seja chamado. Na maioria dos casos, você pode considerar a concessão associada à accessToken foi revogado.
  • invalid_request: o token não é revogável. Verifique se accessToken é uma credencial válida do Google OAuth 2.0.
error_description String. Indefinida em caso de sucesso. O texto ASCII legível fornece informações adicionais sobre error. Os desenvolvedores podem usar isso para entender melhor o erro que ocorreu. A string error_description está somente 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 é revogável.