MDN wants to talk to developers like you: https://qsurvey.mozilla.com/s3/8d22564490d8

identity.launchWebAuthFlow

Performs the first part of an OAuth2 flow, including user authentication and client authorization.

This function's only mandatory parameter is the service provider's authorization URL, which must contain a number of URL parameters including the redirect URL and the add-on's client ID. The service provider then:

  • authenticates the user with the service provider, if necessary (that is: if they are not already signed in)
  • asks the user to authorize the add-on to access the requested data, if necessary (that is: if the user has not already authorized the add-on)

Note that if neither authentication or authorization are needed, then this function will complete silently, without any user interaction.

This function also takes an optional parameter interactive: if this is omitted or set to false, then the flow is forced to complete silently. In this case, if the user has to authenticate or authorize, then the operation will just fail.

This function returns a Promise: if authentication and authorization were successful, the promise is fulfilled with a redirect URL that contains a number of URL parameters. Depending on the OAuth2 flow implemented by the service provider in question, the add-on will need to go through further steps to get a valid access code, which it can then use to access the user's data.

If there's any error, the promise is rejected with an error message. Error conditions may include:

  • the service provider's URL could not be reached
  • the client ID did not match the ID of a registered client
  • the redirect URL did not match any redirect URLs registered for this client
  • the user did not authenticate successfully
  • the user did not authorize the add-on
  • the interactive parameter was omitted or false, but user interaction would have been needed to authorize the add-on.

Syntax

var authorizing = browser.identity.launchWebAuthFlow(
  details   // object
)

Parameters

details
object. Options for the flow, containing the following properties:
url

string. The URL offered by the OAuth2 service provider to get an access token. The details of this URL should be given in the documentation for the service provider in question, but the URL parameters should always include:

  • client_id: this should match the client ID that the service provider gave you when you registered the add-on. See Registering your add-on.
  • redirect_uri: this represents the URI your add-on is redirected to when the flow has finished. See Getting the redirect URL.
interactive Optional

boolean. If omitted or false, forces the flow to complete silently, without any user interaction.

If the user is already signed in and has already granted access for the add-on, then launchWebAuthFlow() can complete silently, without any user interaction. Otherwise (if the service provider needs the user to sign in, or to authorize the add-on), then launchWebAuthFlow() will prompt the user: that is, the flow will be interactive.

Add-ons should not launch interactive flows except in response to a user action. However, sometimes add-ons still want to access the user's data without a direct user action (for example, imagine an add-on that wants to access data when the browser launches).

This is the purpose of interactive: if you omit interactive or set it to false, then the flow is forced to conclude silently: if the service provider needs to interact with the user, the flow will just fail. So as a general rule: set interactive to true if you're launching the flow in response to a user action, and omit it otherwise.

Return value

A Promise. If the add-on is authorized successfully, this will be fulfilled with a string containing the redirect URL. The URL will include a parameter that either is an access token or can be exchanged for an access token, using the documented flow for the particular service provider. 

Browser compatibility

ChromeEdgeFirefoxFirefox for AndroidOpera
Basic supportYesNo53.053.0Yes

Examples

This function authorizes an add-on to access a user's Google data, according to the documentation at https://developers.google.com/identity/protocols/OAuth2UserAgent. Validation of the returned access token isn't shown here:

function validate(redirectURL) {
  // validate the access token
}

function authorize() {
  const redirectURL = browser.identity.getRedirectURL();
  const clientID = "664583959686-fhvksj46jkd9j5v96vsmvs406jgndmic.apps.googleusercontent.com";  
  const scopes = ["openid", "email", "profile"];
  let authURL = "https://accounts.google.com/o/oauth2/auth";
  authURL += `?client_id=${clientID}`;
  authURL += `&response_type=token`;
  authURL += `&redirect_uri=${encodeURIComponent(redirectURL)}`;
  authURL += `&scope=${encodeURIComponent(scopes.join(' '))}`;

  return browser.identity.launchWebAuthFlow({
    interactive: true,
    url: authURL
  });
}

function getAccessToken() {
  return authorize().then(validate);
}

Example add-ons

Acknowledgements

This API is based on Chromium's identity API.

Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.

Document Tags and Contributors

 Contributors to this page: wbamberg
 Last updated by: wbamberg,