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 vai mudar durante a vida útil da conta.

AccountStatus

Chrome 84 ou mais recente

Enumeração

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

"ANY"
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 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

  • e-mail

    string

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

  • ID

    string

    Um identificador exclusivo da conta. Esse ID não vai mudar durante a vida útil da conta. Fica vazio se o usuário não estiver conectado ou (no M41 ou versões mais recentes) se a permissão de manifesto identity.email não estiver especificada.

TokenDetails

Propriedades

  • conta

    AccountInfo opcional

    O ID da conta cujo token será retornado. Se não for especificado, a função vai 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 mais recente

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

  • interativo

    booleano opcional

    Para buscar um token, talvez seja necessário que o usuário faça login no Chrome ou aprove os escopos solicitados pelo aplicativo. Se a flag interativa for true, getAuthToken vai solicitar ao usuário conforme necessário. Quando a flag é false ou omitida, getAuthToken retorna falha sempre que um aviso for 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 mais recente

    Se é necessário encerrar launchWebAuthFlow 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 após a aprovação do timeoutMsForNonInteractive. Isso é útil para provedores de identidade que usam JavaScript para fazer redirecionamentos depois que a página é carregada.

  • interativo

    booleano opcional

    Indica 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 destinada a ser exibida.

    Se a flag 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 definição de timeoutMsForNonInteractive para dar à página a chance de realizar redirecionamentos.

  • timeoutMsForNonInteractive

    number optional

    Chrome 113 ou mais recente

    O tempo máximo, em milissegundos, que launchWebAuthFlow pode 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()

Promise Chrome 87 ou mais recente 
chrome.identity.clearAllCachedAuthTokens(
  callback?: function,
): Promise<void>

Redefine o estado da API Identity:

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

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promise<void>

    Chrome 106 ou mais recente

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getAccounts()

Promise Canal Dev 
chrome.identity.getAccounts(
  callback?: function,
): Promise<AccountInfo[]>

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

O getAccounts só é compatível com o canal de desenvolvimento.

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (accounts: AccountInfo[]) => void

Retorna

  • Promise<AccountInfo[]>

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getAuthToken()

Promise 
chrome.identity.getAuthToken(
  details?: TokenDetails,
  callback?: function,
): Promise<GetAuthTokenResult>

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

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

Para uma boa experiência do usuário, é importante que as solicitações de token interativas sejam iniciadas pela interface do seu app, explicando para que serve a autorização. Se você não fizer isso, os usuários vão receber solicitações de autorização ou telas de login do Chrome sem contexto, caso não tenham feito login. Em particular, não use getAuthToken de forma interativa quando o app for iniciado pela primeira vez.

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

Parâmetros

Retorna

  • Chrome 105 ou mais recente

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getProfileUserInfo()

Promise 
chrome.identity.getProfileUserInfo(
  details?: ProfileDetails,
  callback?: function,
): Promise<ProfileUserInfo>

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

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

Essa API é diferente de 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

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getRedirectURL()

chrome.identity.getRedirectURL(
  path?: string,
): 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()

Promise 
chrome.identity.launchWebAuthFlow(
  details: WebAuthFlowDetails,
  callback?: function,
): Promise<string | undefined>

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

Esse método permite fluxos de autenticação com provedores de identidade que não são do Google ao iniciar uma visualização da Web e navegar até o primeiro URL no fluxo de autenticação do provedor. Quando o provedor redireciona para um URL que corresponde 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 do app, explicando a finalidade da autorização. Se você não fizer isso, seus 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 app 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

  • Promise<string | undefined>

    Chrome 106 ou mais recente

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

removeCachedAuthToken()

Promise 
chrome.identity.removeCachedAuthToken(
  details: InvalidTokenDetails,
  callback?: function,
): Promise<void>

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

Se um token de acesso for considerado inválido, ele deverá ser transmitido para removeCachedAuthToken e removido do cache. Em seguida, o app pode recuperar 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

  • Promise<void>

    Chrome 106 ou mais recente

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

Eventos

onSignInChanged

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

Acionada quando o estado de login muda 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