Skip to content

identity.md

Latest commit

 

History

History
201 lines (135 loc) · 6.98 KB

identity.md

File metadata and controls

201 lines (135 loc) · 6.98 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

isAvailableIdentity

isAvailableIdentity(method?: ApiMethodName<typeof chrome.identity>): boolean

The optional method is a native function name, for example isAvailableIdentity("launchWebAuthFlow"). Import the public ApiMethodName type from @addon-core/browser for your own typed helpers. This checks callable presence without invoking the method; permissions and argument support still require handling.

Returns true when the identity namespace is present on the API selected by browser() in the current context. Returns false if the namespace or WebExtension environment is absent, or if accessing it throws. The check is synchronous, does not log, and reads the current API on every call without caching. Without an argument, it checks namespace presence only. Pass a native method name to also check that it is callable. Neither form verifies permissions, argument support, or a successful operation. See method availability.

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

if (isAvailableIdentity()) {
    // The namespace is present; handle operation-specific failures when using it.
}

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.

Pass redirect_uri as a query parameter of details.url, as shown above. It is not a separate LaunchWebAuthFlowDetails property: Firefox rejects such a property before starting the flow. Firefox accepts its generated redirect URL or, from Firefox 86, the special loopback URL http://127.0.0.1/mozoauth2/<subdomain-of-getIdentityRedirectUrl()>. Arbitrary callback URLs are not supported. See Firefox redirect URL setup.

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.