Skip to content

identity.md

Latest commit

 

History

History
170 lines (111 loc) · 5.41 KB

identity.md

File metadata and controls

170 lines (111 loc) · 5.41 KB
Raw

identity

Documentation:

A promise-based wrapper for the WebExtension identity API. Chrome exposes the full API surface. Firefox, Edge, and Opera should use the portable OAuth flow with getIdentityRedirectUrl() and launchWebAuthFlow(). Safari does not support this API.

Browser support notes

  • Chrome: supports the full chrome.identity API, except the underlying getAccounts() API is Chrome Dev channel only. This wrapper uses the callback form for Chrome-style runtimes because it works across Manifest V2 and Manifest V3.
  • Firefox: supports the portable browser.identity.launchWebAuthFlow() promise API and getRedirectURL().
  • Edge: use launchWebAuthFlow() for portable OAuth. getAuthToken() and the underlying getAccounts() API are officially unsupported even if feature detection sees the methods.
  • Opera: supports the portable web auth flow in Chromium-based builds.
  • Safari: Identity API is not supported.

Manifest

For Chrome OAuth token helpers, add identity and the oauth2 manifest section:

{
  "permissions": ["identity"],
  "oauth2": {
    "client_id": "client-id.apps.googleusercontent.com",
    "scopes": ["profile", "email"]
  }
}

For profile email data, add identity.email:

{
  "permissions": ["identity", "identity.email"]
}

Interactive authorization flows should be started from a user action, such as a button click.

Methods

Events

getIdentityRedirectUrl

getIdentityRedirectUrl(path?: string): string

Generates the extension redirect URL for an OAuth flow.

import {getIdentityRedirectUrl} from "@addon-core/browser";

const redirectUrl = getIdentityRedirectUrl("oauth");

In Chromium browsers this usually returns a URL like https://<extension-id>.chromiumapp.org/oauth.

launchWebAuthFlow

launchWebAuthFlow(details: LaunchWebAuthFlowDetails): Promise<string | undefined>

Starts a browser-managed OAuth flow and resolves with the final redirect URL. This is the recommended portable API for Firefox, Edge, Opera, and non-Google providers.

import {getIdentityRedirectUrl, launchWebAuthFlow} from "@addon-core/browser";

const redirectUrl = getIdentityRedirectUrl("oauth");
const url = new URL("https://accounts.example.com/oauth/authorize");
url.searchParams.set("redirect_uri", redirectUrl);

const responseUrl = await launchWebAuthFlow({
  interactive: true,
  url: url.toString(),
});

This wrapper uses the callback form in Chrome-style runtimes to avoid callbackless Manifest V2 flows hanging, and the Promise form in Firefox where callbacks are not accepted.

LaunchWebAuthFlowDetails also accepts redirect_uri for Firefox. This option is Firefox-only, supported since Firefox 63; loopback redirect URIs are supported since Firefox 86.

getAuthToken

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

Gets a Chrome OAuth2 access token using the manifest oauth2 configuration or the provided scopes. The wrapper always resolves to { token, grantedScopes }, including callback-based Chrome runtimes that return those values as separate callback arguments.

import {getAuthToken} from "@addon-core/browser";

const {token} = await getAuthToken({interactive: true});

This method is Chrome-focused. In Edge, it is officially unsupported even if present.

removeCachedAuthToken

removeCachedAuthToken(details: chrome.identity.InvalidTokenDetails): Promise<void>

Removes an OAuth2 access token from Chrome's token cache.

clearAllCachedAuthTokens

clearAllCachedAuthTokens(): Promise<void>

Clears all cached auth tokens and authorization state managed by the Identity API.

getProfileUserInfo

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

Returns profile email and ID information. Requires the identity.email permission; otherwise Chrome returns empty fields.

getIdentityAccounts

getIdentityAccounts(): Promise<chrome.identity.AccountInfo[]>

Returns accounts present in the Chrome profile. This API is Chrome Dev channel only and should not be used for stable product logic.

onIdentitySignInChanged

onIdentitySignInChanged(callback: (account: chrome.identity.AccountInfo, signedIn: boolean) => void): () => void

Fires when the sign-in state changes for an account in the user's profile. Returns an unsubscribe function.