chrome.identity

Description
Use the chrome.identity API to get OAuth2 access tokens.
Permissions
identity

Summary

Types
AccountInfo
AccountStatus
InvalidTokenDetails
ProfileDetails
ProfileUserInfo
TokenDetails
WebAuthFlowDetails
Methods
clearAllCachedAuthTokens
clearAllCachedAuthTokens(callback: function): void
getAccounts
getAccounts(callback: function): void
getAuthToken
getAuthToken(details?: TokenDetails, callback?: function): void
getProfileUserInfo
getProfileUserInfo(details?: ProfileDetails, callback: function): void
getRedirectURL
getRedirectURL(path?: string): string
launchWebAuthFlow
launchWebAuthFlow(details: WebAuthFlowDetails, callback: function): void
removeCachedAuthToken
removeCachedAuthToken(details: InvalidTokenDetails, callback?: function): void
Events
onSignInChanged

Types

AccountInfo

Properties

id
string
A unique identifier for the account. This ID will not change for the lifetime of the account.

AccountStatus

Chrome 84+

Enum

"SYNC", or "ANY"

InvalidTokenDetails

Properties

token
string
The specific token that should be removed from the cache.

ProfileDetails

Chrome 84+

Properties

accountStatus
AccountStatus optional
A status of the primary account signed into a profile whose ProfileUserInfo should be returned. Defaults to SYNC account status.

ProfileUserInfo

Properties

email
string
An email address for the user account signed into the current profile. Empty if the user is not signed in or the identity.email manifest permission is not specified.
id
string
A unique identifier for the account. This ID will not change for the lifetime of the account. Empty if the user is not signed in or (in M41+) the identity.email manifest permission is not specified.

TokenDetails

Properties

account
AccountInfo optional
The account ID whose token should be returned. If not specified, the function will use an account from the Chrome profile: the Sync account if there is one, or otherwise the first Google web account.
enableGranularPermissions
boolean optional
Chrome 87+
The enableGranularPermissions flag allows extensions to opt-in early to the granular permissions consent screen, in which requested permissions are granted or denied individually.
interactive
boolean optional
Fetching a token may require the user to sign-in to Chrome, or approve the application's requested scopes. If the interactive flag is true, getAuthToken will prompt the user as necessary. When the flag is false or omitted, getAuthToken will return failure any time a prompt would be required.
scopes
string[] optional
A list of OAuth2 scopes to request.
When the scopes field is present, it overrides the list of scopes specified in manifest.json.

WebAuthFlowDetails

Properties

interactive
boolean optional
Whether to launch auth flow in interactive mode.
Since some auth flows may immediately redirect to a result URL, launchWebAuthFlow hides its web view until the first navigation either redirects to the final URL, or finishes loading a page meant to be displayed.
If the interactive flag is true, the window will be displayed when a page load completes. If the flag is false or omitted, launchWebAuthFlow will return with an error if the initial navigation does not complete the flow.
url
string
The URL that initiates the auth flow.

Methods

clearAllCachedAuthTokens

clearAllCachedAuthTokens(callback: function): void

Chrome 87+

Resets the state of the Identity API:

Removes all OAuth2 access tokens from the token cache
Removes user's account preferences
De-authorizes the user from all auth flows

Parameters

callback
function
Called when the state has been cleared.
The parameter should be a function that looks like this:
() => {...}

getAccounts

getAccounts(callback: function): void

Dev channel

Retrieves a list of AccountInfo objects describing the accounts present on the profile.

getAccounts is only supported on dev channel.

Parameters

callback
function
The parameter should be a function that looks like this:
(accounts: AccountInfo[]) => {...}
- accounts
  AccountInfo[]

getAuthToken

getAuthToken(details?: TokenDetails, callback?: function): void

Gets an OAuth2 access token using the client ID and scopes specified in the oauth2 section of manifest.json.

The Identity API caches access tokens in memory, so it's ok to call getAuthToken non-interactively any time a token is required. The token cache automatically handles expiration.

For a good user experience it is important interactive token requests are initiated by UI in your app explaining what the authorization is for. Failing to do this will cause your users to get authorization requests, or Chrome sign in screens if they are not signed in, with with no context. In particular, do not use getAuthToken interactively when your app is first launched.

Parameters

details
TokenDetails optional
Token options.
callback
function optional
Called with an OAuth2 access token as specified by the manifest, or undefined if there was an error. The grantedScopes parameter is populated since Chrome 87. When available, this parameter contains the list of granted scopes corresponding with the returned token.
If you specify the parameter, it should be a function that looks like this:
(token?: string, grantedScopes?: string[]) => {...}
- token
  string optional
- grantedScopes
  string[] optional
  Chrome 86+

getProfileUserInfo

getProfileUserInfo(details?: ProfileDetails, callback: function): void

Retrieves email address and obfuscated gaia id of the user signed into a profile.

Requires the identity.email manifest permission. Otherwise, returns an empty result.

This API is different from identity.getAccounts in two ways. The information returned is available offline, and it only applies to the primary account for the profile.

Parameters

details
ProfileDetails optional
Chrome 84+
Profile options.
callback
function
Called with the ProfileUserInfo of the primary Chrome account, of an empty ProfileUserInfo if the account with given details doesn't exist.
The parameter should be a function that looks like this:
(userInfo: ProfileUserInfo) => {...}
- userInfo
  ProfileUserInfo

getRedirectURL

getRedirectURL(path?: string): string

Generates a redirect URL to be used in launchWebAuthFlow.

The generated URLs match the pattern https://<app-id>.chromiumapp.org/*.

Parameters

path
string optional
The path appended to the end of the generated URL.

Returns

return
string

launchWebAuthFlow

launchWebAuthFlow(details: WebAuthFlowDetails, callback: function): void

Starts an auth flow at the specified URL.

This method enables auth flows with non-Google identity providers by launching a web view and navigating it to the first URL in the provider's auth flow. When the provider redirects to a URL matching the pattern https://<app-id>.chromiumapp.org/*, the window will close, and the final redirect URL will be passed to the callback function.

For a good user experience it is important interactive auth flows are initiated by UI in your app explaining what the authorization is for. Failing to do this will cause your users to get authorization requests with no context. In particular, do not launch an interactive auth flow when your app is first launched.

Parameters

details
WebAuthFlowDetails
WebAuth flow options.
callback
function
Called with the URL redirected back to your application.
The parameter should be a function that looks like this:
(responseUrl?: string) => {...}
- responseUrl
  string optional

removeCachedAuthToken

removeCachedAuthToken(details: InvalidTokenDetails, callback?: function): void

Removes an OAuth2 access token from the Identity API's token cache.

If an access token is discovered to be invalid, it should be passed to removeCachedAuthToken to remove it from the cache. The app may then retrieve a fresh token with getAuthToken.

Parameters

details
InvalidTokenDetails
Token information.
callback
function optional
Called when the token has been removed from the cache.
If you specify the parameter, it should be a function that looks like this:
() => {...}

Events

onSignInChanged

onSignInChanged.addListener(listener: function)

Fired when signin state changes for an account on the user's profile.

Event

listener
function
The listener parameter should be a function that looks like this:
(account: AccountInfo, signedIn: boolean) => {...}
- account
  AccountInfo
- signedIn
  boolean