chrome.identity

Descrição

Use a API chrome.identity para receber tokens de acesso do OAuth2.

Permissões

identity

Tipos

AccountInfo

Propriedades

  • id

    string

    Identificador exclusivo da conta. Esse ID não será alterado durante todo o ciclo de vida da conta.

AccountStatus

Chrome 84 ou superior

Enumeração

"SYNC"
Especifica que a sincronização está ativada para a conta principal.

"QUALQUER"
Especifica a existência de uma conta principal, se houver.

GetAuthTokenResult

Chrome 105 ou mais recente

Propriedades

  • grantedScopes

    string[] opcional

    Uma lista de escopos do OAuth2 concedidos à extensão.

  • token

    string opcional

    O token específico associado à solicitação.

InvalidTokenDetails

Propriedades

  • token

    string

    O token específico que deve ser removido do cache.

ProfileDetails

Chrome 84 ou superior

Propriedades

  • accountStatus

    AccountStatus opcional

    Um status da conta principal conectada a um perfil cujo ProfileUserInfo precisa ser retornado. O padrão é o status da conta: SYNC.

ProfileUserInfo

Propriedades

  • e-mail

    string

    Um endereço de e-mail da conta de usuário conectada ao perfil atual. Vai ser vazio se o usuário não tiver feito login ou se a permissão de manifesto identity.email não estiver especificada.

  • id

    string

    Identificador exclusivo da conta. Esse ID não será alterado durante todo o ciclo de vida da conta. Vai ser vazio se o usuário não estiver conectado ou (na versão M41 ou mais recente) a permissão de manifesto identity.email não estiver especificada.

TokenDetails

Propriedades

  • conta

    AccountInfo opcional

    O ID da conta cujo token deve ser retornado. Se não for especificada, a função usará uma conta do perfil do Chrome: a conta de sincronização, se houver uma, ou a primeira conta da Web do Google.

  • enableGranularPermissions

    booleano opcional

    Chrome 87 ou superior

    A flag enableGranularPermissions permite que as extensões ativem antecipadamente a tela de consentimento de permissões granulares, em que as permissões solicitadas são concedidas ou negadas individualmente.

  • interativo

    booleano opcional

    A busca de um token pode exigir que o usuário faça login no Google Chrome ou aprove os escopos solicitados do aplicativo. Se a flag interativa for true, o getAuthToken vai pedir ao usuário conforme necessário. Quando a flag é false ou omitida, getAuthToken retorna uma falha sempre que um comando é necessário.

  • escopos

    string[] opcional

    Uma lista de escopos do OAuth2 a serem solicitados.

    Quando o campo scopes está presente, ele substitui a lista de escopos especificados em manifest.json.

WebAuthFlowDetails

Propriedades

  • abortOnLoadForNonInteractive

    booleano opcional

    Chrome 113 ou versões mais recentes

    Define se launchWebAuthFlow é encerrado para solicitações não interativas após o carregamento da página. Esse parâmetro não afeta os fluxos interativos.

    Quando definido como true (padrão), o fluxo será encerrado imediatamente após o carregamento da página. Quando definido como false, o fluxo só será encerrado depois que timeoutMsForNonInteractive for transmitido. Isso é útil para provedores de identidade que usam JavaScript para executar redirecionamentos após o carregamento da página.

  • interativo

    booleano opcional

    Define se o fluxo de autenticação será iniciado no modo interativo.

    Como alguns fluxos de autenticação podem redirecionar imediatamente para um URL de resultado, o launchWebAuthFlow oculta a visualização da Web até que a primeira navegação redirecione para o URL final ou termine de carregar uma página que será exibida.

    Se a sinalização interactive for true, a janela será exibida quando um carregamento de página for concluído. Se a flag for false ou omitida, launchWebAuthFlow vai retornar um erro se a navegação inicial não concluir o fluxo.

    Para fluxos que usam JavaScript para redirecionamento, abortOnLoadForNonInteractive pode ser definido como false em combinação com a configuração timeoutMsForNonInteractive para dar à página a chance de executar qualquer redirecionamento.

  • timeoutMsForNonInteractive

    número opcional

    Chrome 113 ou versões mais recentes

    O tempo máximo, em milissegundos, em que launchWebAuthFlow tem permissão para ser executado no modo não interativo no total. Só tem efeito se interactive for false.

  • url

    string

    O URL que inicia o fluxo de autenticação.

Métodos

clearAllCachedAuthTokens()

Promessa Chrome 87 ou versão mais recente 
chrome.identity.clearAllCachedAuthTokens(
  callback?: function,
)

Redefine o estado da API Identity:

  • Remove todos os tokens de acesso OAuth2 do cache de tokens
  • Remove as preferências da conta do usuário
  • Desautoriza o usuário em todos os fluxos de autenticação

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 106 ou versões mais recentes

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

getAccounts()

Promessa Canal de Desenvolvedor 
chrome.identity.getAccounts(
  callback?: function,
)

Recupera uma lista de objetos AccountInfo que descrevem as contas presentes no perfil.

getAccounts só é compatível com o Canal de Desenvolvedor.

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (accounts: AccountInfo[]) => void

Retorna

  • Promise&lt;AccountInfo[]&gt;

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

getAuthToken()

Promessa 
chrome.identity.getAuthToken(
  details?: TokenDetails,
  callback?: function,
)

Recebe um token de acesso OAuth2 usando o ID do cliente e os escopos especificados na seção oauth2 do arquivo manifest.json.

A API Identity armazena tokens de acesso em cache na memória. Portanto, não há problema em chamar getAuthToken de forma não interativa sempre que um token for necessário. O cache de token lida automaticamente com a expiração.

Para uma boa experiência do usuário, é importante que as solicitações de token interativo sejam iniciadas pela IU no aplicativo, explicando para que serve a autorização. Se isso não for feito, os usuários receberão solicitações de autorização ou telas de login no Chrome, se não estiverem conectados, sem contexto. Em especial, não use getAuthToken interativamente quando o app for iniciado pela primeira vez.

Observação: quando chamada com um callback, em vez de retornar um objeto, essa função retornará as duas propriedades como argumentos separados transmitidos ao callback.

Parâmetros

Retorna

  • Promise&lt;GetAuthTokenResult&gt;

    Chrome 105 ou mais recente

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

getProfileUserInfo()

Promessa 
chrome.identity.getProfileUserInfo(
  details?: ProfileDetails,
  callback?: function,
)

Recupera o endereço de e-mail e o ID ofuscado do GAIA do usuário conectado a um perfil.

Requer a permissão de manifesto identity.email. Caso contrário, retorna um resultado vazio.

Essa API é diferente de Identity.getAccounts de duas maneiras. As informações retornadas ficam disponíveis off-line e se aplicam somente à conta principal do perfil.

Parâmetros

Retorna

  • Promise&lt;ProfileUserInfo&gt;

    Chrome 106 ou versões mais recentes

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

getRedirectURL()

chrome.identity.getRedirectURL(
  path?: string,
)

Gera um URL de redirecionamento para ser usado em launchWebAuthFlow.

Os URLs gerados correspondem ao padrão https://<app-id>.chromiumapp.org/*.

Parâmetros

  • caminho

    string opcional

    O caminho anexado ao final do URL gerado.

Retorna

  • string

launchWebAuthFlow()

Promessa 
chrome.identity.launchWebAuthFlow(
  details: WebAuthFlowDetails,
  callback?: function,
)

Inicia um fluxo de autenticação no URL especificado.

Esse método ativa fluxos de autenticação com provedores de identidade que não são do Google iniciando uma visualização da Web e navegando para o primeiro URL no fluxo de autenticação do provedor. Quando o provedor redireciona para um URL correspondente ao padrão https://<app-id>.chromiumapp.org/*, a janela é fechada, e o URL de redirecionamento final é transmitido para a função callback.

Para uma boa experiência do usuário, é importante que os fluxos de autenticação interativos sejam iniciados pela interface no app, explicando para que serve a autorização. Se isso não for feito, os usuários vão receber solicitações de autorização sem contexto. Em particular, não inicie um fluxo de autenticação interativo quando o aplicativo for iniciado pela primeira vez.

Parâmetros

  • Opções de fluxo do WebAuth.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (responseUrl?: string) => void

    • responseUrl

      string opcional

Retorna

  • Promessa<string | indefinido>

    Chrome 106 ou versões mais recentes

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

removeCachedAuthToken()

Promessa 
chrome.identity.removeCachedAuthToken(
  details: InvalidTokenDetails,
  callback?: function,
)

Remove um token de acesso OAuth2 do cache de tokens da API Identity.

Se um token de acesso for inválido, ele deverá ser transmitido para removeCachedAuthToken para removê-lo do cache. Assim, o app pode extrair um novo token com getAuthToken.

Parâmetros

  • Informações do token.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 106 ou versões mais recentes

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

Eventos

onSignInChanged

chrome.identity.onSignInChanged.addListener(
  callback: function,
)

Disparado quando o estado de login é alterado para uma conta no perfil do usuário.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (account: AccountInfo, signedIn: boolean) => void