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
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
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
Propriedades
-
accountStatus
AccountStatus opcional
Um status da conta principal conectada a um perfil cujo
ProfileUserInfo
precisa ser retornado. O padrão é o status da contaSYNC
.
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 recenteA 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
, ogetAuthToken
vai perguntar ao usuário conforme necessário. Quando a sinalização forfalse
ou omitida,getAuthToken
retornará uma falha sempre que uma solicitação for necessária. -
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 no manifest.json.
WebAuthFlowDetails
Propriedades
-
abortOnLoadForNonInteractive
booleano opcional
Chrome 113 ou mais recenteDefine 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 comofalse
, o fluxo só vai terminar após a transmissão detimeoutMsForNonInteractive
. 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
fortrue
, a janela será exibida quando o carregamento de uma página for concluído. Se a flag forfalse
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 comofalse
em combinação com a configuraçãotimeoutMsForNonInteractive
para dar à página a chance de realizar qualquer redirecionamento. -
timeoutMsForNonInteractive
número opcional
Chrome 113 ou mais recenteO período máximo, em milissegundos, de execução de
launchWebAuthFlow
no modo não interativo no total. Só tem efeito seinteractive
forfalse
. -
url
string
O URL que inicia o fluxo de autenticação.
Métodos
clearAllCachedAuthTokens()
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 recentePromessas 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()
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
-
contas
-
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()
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
-
detalhes
TokenDetails opcional
Opções de token.
-
callback
função optional
O parâmetro
callback
tem esta aparência:(result: GetAuthTokenResult) => void
-
resultadoChrome 105 ou mais recente
-
Retorna
-
Promise<GetAuthTokenResult>
Chrome 105 ou mais recentePromessas 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()
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
-
detalhes
ProfileDetails opcional
Chrome 84 ou mais recenteOpções do perfil.
-
callback
função optional
O parâmetro
callback
tem esta aparência:(userInfo: ProfileUserInfo) => void
-
userInfo
-
Retorna
-
Promise<ProfileUserInfo>
Chrome 106 ou mais recentePromessas 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()
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
-
detalhes
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 recentePromessas 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()
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
-
detalhes
Informações do token.
-
callback
função optional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 106 ou mais recentePromessas 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
-
conta
-
signedIn
boolean
-