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 extension'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 extension to access the requested data, if necessary (that is: if the user has not already authorized the extension)
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 extension 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 extension
- the
interactive
parameter was omitted or false, but user interaction would have been needed to authorize the extension.