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) 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, 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 antecipadamente 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 comando 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

    número 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 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 optional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 106 ou mais recente

    Retorna uma promessa que é resolvida quando o estado é limpo.

    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 optional

    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()

Promessa 
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, seus usuários vão receber solicitações de autorização ou telas de login do Chrome sem contexto. 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

    Retorna uma promessa que é resolvida com um token de acesso do OAuth2, conforme especificado pelo manifesto, ou rejeita se houver um erro. O parâmetro grantedScopes é preenchido desde o Chrome 87. Quando disponível, esse parâmetro contém a lista de escopos concedidos correspondentes ao token retornado.

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

getProfileUserInfo()

Promessa 
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 se aplicam apenas à conta principal do perfil.

Parâmetros

Retorna

  • Promise<ProfileUserInfo>

    Chrome 106 ou mais recente

    Retorna uma promessa que é resolvida com o ProfileUserInfo da conta principal do Chrome ou um ProfileUserInfo vazio se a conta com o details especificado não existir.

    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()

Promessa 
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 pedidos de autorização sem contexto. Em especial, 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 optional

    O parâmetro callback tem esta aparência: 

    (responseUrl?: string) => void

    • responseUrl

      string opcional

Retorna

  • Promise<string | undefined>

    Chrome 106 ou mais recente

    Retorna uma promessa que é resolvida com o URL redirecionado de volta ao seu aplicativo.

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

removeCachedAuthToken()

Promessa 
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 optional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 106 ou mais recente

    Retorna uma promessa que é resolvida quando o token é removido do cache.

    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