chrome.identity

Descrição

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

Permissões

identity

Tipos

AccountInfo

Propriedades

  • id

    string

    Um identificador exclusivo da conta. Esse ID não mudará durante a vida útil da conta.

AccountStatus

Chrome 84 ou mais recente

Tipo enumerado

"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 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 mais recente

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

  • email

    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 estiver conectado ou se a permissão de manifesto identity.email não for especificada.

  • id

    string

    Um identificador exclusivo da conta. Esse ID não mudará durante a vida útil da conta. Vazio se o usuário não estiver conectado ou (no M41+) a permissão de manifesto identity.email não for especificada.

TokenDetails

Propriedades

  • conta

    AccountInfo opcional

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

  • enableGranularPermissions

    booleano opcional

    Chrome 87 ou mais recente

    A sinalização 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 Chrome ou aprove os escopos solicitados do aplicativo. Se a sinalização interativa for true, o getAuthToken vai perguntar ao usuário conforme necessário. Quando a sinalização for false ou omitida, getAuthToken retornará uma falha sempre que uma solicitação for necessária.

  • scopes

    string[] opcional

    Uma lista de escopos do OAuth2 a serem solicitados.

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

WebAuthFlowDetails

Propriedades

  • abortOnLoadForNonInteractive

    booleano opcional

    Chrome 113 ou mais recente

    Define se launchWebAuthFlow deve ser encerrado para solicitações não interativas após o carregamento da página. Esse parâmetro não afeta 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ó vai terminar após a transmissão de timeoutMsForNonInteractive. Isso é útil para provedores de identidade que usam JavaScript para realizar 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 a ser exibida.

    Se a sinalização interactive for true, a janela será exibida quando o carregamento de uma página for concluído. Se a flag for false ou omitida, launchWebAuthFlow vai retornar com 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 realizar qualquer redirecionamento.

  • timeoutMsForNonInteractive

    número opcional

    Chrome 113 ou mais recente

    O período máximo, em milissegundos, de execução de launchWebAuthFlow 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 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 optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 106 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

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 optional

    O parâmetro callback tem esta aparência: 

    (accounts: AccountInfo[])=>void

Retorna

  • Promise<AccountInfo[]>

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

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 manifest.json.

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

Para uma boa experiência do usuário, é importante que as solicitações de token interativo sejam iniciadas pela IU no seu aplicativo explicando para que serve a autorização. Se isso não for feito, seus usuários vão receber solicitações de autorização ou telas de login do 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 retorno de chamada, em vez de retornar um objeto, essa função retornará as duas propriedades como argumentos separados passados para o retorno de chamada.

Parâmetros

Retorna

  • Chrome 105 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

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 da "identity.getAccounts" de duas maneiras. As informações retornadas estão disponíveis off-line e só se aplicam à conta principal do perfil.

Parâmetros

Retorna

  • Promise<ProfileUserInfo>

    Chrome 106 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

getRedirectURL()

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

Gera um URL de redirecionamento a ser usado no 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 os fluxos de autenticação com provedores de identidade que não são do Google iniciando uma visualização da Web e navegando até 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 IU no seu aplicativo explicando para que serve a autorização. Se isso não for feito, seus usuários vão receber solicitações de autorização sem contexto. Em especial, não inicie um fluxo de autenticação interativo quando seu aplicativo for iniciado pela primeira vez.

Parâmetros

  • Opções de fluxo do WebAuth.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    (responseUrl?: string)=>void

    • responseUrl

      string opcional

Retorna

  • Promessa<string|indefinida>

    Chrome 106 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

removeCachedAuthToken()

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

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

Se for detectado que um token de acesso é inválido, transmita-o para removeCachedAuthToken a fim de removê-lo do cache. O app vai poder extrair um novo token com getAuthToken.

Parâmetros

  • Informações do token.

  • callback

    função optional

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 106 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

Eventos

onSignInChanged

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

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

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

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