browser.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 o ciclo de vida da conta.

AccountStatus

Chrome 84+ browser.* desde o Chrome 148

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+ browser.* desde o Chrome 148

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+ browser.* desde o Chrome 148

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 para a 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 for especificada.

  • ID

    string

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

TokenDetails

Propriedades

  • conta

    AccountInfo opcional

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

  • enableGranularPermissions

    booleano opcional

    Chrome 87+ browser.* desde o Chrome 148

    A flag enableGranularPermissions permite que as extensões aceitem 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, o usuário pode precisar fazer login no Chrome ou aprovar 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 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 especificada em manifest.json.

WebAuthFlowDetails

Propriedades

  • abortOnLoadForNonInteractive

    booleano opcional

    Chrome 113+ browser.* desde o Chrome 148

    Se launchWebAuthFlow deve ser 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 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

    Se o fluxo de autenticação deve 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 deve ser exibida.

    Se a flag interactive for true, a janela será exibida quando o carregamento de página for concluído. Se a flag for false ou for 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 realizar redirecionamentos.

  • timeoutMsForNonInteractive

    número optional

    Chrome 113+ browser.* desde o Chrome 148

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

  • url

    string

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

Métodos

clearAllCachedAuthTokens()

Chrome 87+ browser.* desde o Chrome 148 
browser.identity.clearAllCachedAuthTokens(): 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
  • Desautoriza o usuário de todos os fluxos de autenticação

Retorna

  • Promessa<void>

    Chrome 106+ browser.* desde o Chrome 148

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

getAccounts()

Canal de Desenvolvedor 
browser.identity.getAccounts(): Promise<AccountInfo[]>

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

getAccounts só tem suporte no canal de desenvolvedor.

Retorna

getAuthToken()

browser.identity.getAuthToken(
  details?: TokenDetails,
): 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 lida automaticamente com a expiração.

Para uma boa experiência do usuário, é importante que as solicitações de token interativas sejam iniciadas pela interface do 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 especial, 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+ browser.* desde o Chrome 148

    Retorna uma promessa que é resolvida com um token de acesso OAuth2, conforme especificado pelo manifesto, ou rejeitada 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.

getProfileUserInfo()

browser.identity.getProfileUserInfo(
  details?: ProfileDetails,
): 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 de manifesto identity.email. 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

  • detalhes

    ProfileDetails opcional

    Chrome 84+ browser.* desde o Chrome 148

    Opções do perfil.

Retorna

  • Promise<ProfileUserInfo>

    Chrome 106+ browser.* desde o Chrome 148

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

getRedirectURL()

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

Gera um URL de redirecionamento a 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()

browser.identity.launchWebAuthFlow(
  details: WebAuthFlowDetails,
): Promise<string | undefined>

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. Para isso, ele inicia uma visualização da Web e navega até o primeiro URL no fluxo de autenticação do provedor. Quando o provedor redirecionar para um URL que corresponda ao padrão https://<app-id>.chromiumapp.org/*, a janela será fechada, e o URL de redirecionamento final será 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 para que serve a autorização. Se você não fizer isso, os usuários vão receber solicitações de autorização sem contexto. Em especial, não inicie um fluxo de autenticação interativo quando o app for aberto pela primeira vez.

Parâmetros

Retorna

  • Promise<string | undefined>

    Chrome 106+ browser.* desde o Chrome 148

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

removeCachedAuthToken()

browser.identity.removeCachedAuthToken(
  details: InvalidTokenDetails,
): 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 precisará ser transmitido para removeCachedAuthToken para ser removido do cache. O app pode recuperar um novo token com getAuthToken.

Parâmetros

Retorna

  • Promessa<void>

    Chrome 106+ browser.* desde o Chrome 148

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

Eventos

onSignInChanged

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

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

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

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