Use external OAuth providers

Article
07/22/2022
3 minutes to read

You can support external or third-party (3P) OAuth providers, such as Google, GitHub, LinkedIn, and Facebook using the updated authenticate() API:

function authenticate(authenticateParameters?: AuthenticateParameters)

The following are added to the authenticate() API to support external OAuth providers:

isExternal parameter
Two placeholder values in the existing url parameter

The following table provides the list of authenticate() API parameters and functions along with their descriptions:

Parameter	Description
`isExternal`	The type of parameter is Boolean, which indicates that the auth window opens in an external browser.
`failureCallback`	The function is called if the authentication fails and the authentication pop-up specifies the reason for failure.
`height`	The preferred height for the pop-up. The value can be ignored if outside the acceptable bounds.
`successCallback`	The function is called if the authentication succeeds, with the result returned from the authentication pop-up. Authcode is the result.
`url`	The URL of 3P app server for the authentication pop-up, with the following two parameter placeholders: - `oauthRedirectMethod`: Pass placeholder in `{}`. This placeholder is replaced by deeplink or web page by Teams platform, which informs app server if the call is coming from mobile platform. - `authId`: This placeholder is replaced by UUID. The app server uses it to maintain session.
`width`	The preferred width for the pop-up. The value can be ignored if outside the acceptable bounds.

For more information on parameters, see authenticate parameters interface.

Add authentication to external browsers

Note

Currently, you can add authentication to external browsers for tabs in mobile only.
Use the beta version of JS SDK to leverage the functionality. Beta versions are available through NPM.

The following image provides the flow to add authentication to external browsers:

authenticate-OAuth

To add authentication to external browsers

Initiate the external auth-login process.

The 3P app calls the SDK function microsoftTeams.authentication.authenticate with isExternal set as true to initiate the external auth-login process.

The passed url contains placeholders for {authId}, and {oauthRedirectMethod}.

microsoftTeams.authentication.authenticate({
   url: 'https://3p.app.server/auth?oauthRedirectMethod={oauthRedirectMethod}&authId={authId}',
   isExternal: true,
   successCallback: function (result) {
   //sucess 
   } failureCallback: function (reason) {
   //failure 
    }
});

Teams link opens in an external browser.

The Teams clients open the URL in an external browser after replacing the placeholders for oauthRedirectMethod and authId with suitable values.

Example
```
 https://3p.app.server/auth?oauthRedirectMethod=deeplink&authId=1234567890 
```

The 3P app server responds.

The 3P app server receives and saves the url with the following two query parameters:

Parameter	Description
`oauthRedirectMethod`	Indicates how the 3P app must send the response of authentication request back to Teams, with one of the two values: deeplink or page.
`authId`	The request-id Teams created for this specific authentication request that needs to be sent back to Teams through deeplink.

Tip

The 3P app can marshal authId, oauthRedirectMethod in the OAuth state query parameter while generating the login URL for the OAuthProvider. The state contains the passed authId and oauthRedirectMethod, when OAuthProvider redirects back to the 3P server and the 3P app uses the values for sending authentication response back to Teams as described in 6. The 3P app server response to Teams.

The 3P app server redirects to specified url.

The 3P app server redirects to OAuth providers auth page in the external browser. The redirect_uri is a dedicated route on the 3P app server. You can register redirect_uri in the OAuth provider’s dev console as static, the parameters need to be sent through the state object.

Example
```
https://accounts.google.com/o/oauth2/v2/auth?redirect_uri=https://3p.app.server/authredirect&state={"authId":"…","oauthRedirectMethod":"…"}&client_id=…    &response_type=code&access_type=offline&scope= … 
```
Sign in to external browser.

User signs in to the external browser. The OAuth providers redirects back to the redirect_uri with the auth code and the state object.

The 3P app server checks and responds to Teams.

The 3P app server handles the response and checks oauthRedirectMethod, which is returned from external OAuth provider in the state object to determine whether the response needs to be returned through the auth-callback deeplink or through web page that calls notifySuccess().

const state = JSON.parse(req.query.state)
if (state.oauthRedirectMethod === 'deeplink') {
   return res.redirect('msteams://teams.microsoft.com/l/auth-callback?authId=${state.authId}&result=${req.query.code}')
}
else {
// continue redirecting to a web-page that will call notifySuccess() – usually this method is used in Teams-Web
…

The 3P app generates a deeplink.

The 3P app generates a deeplink for Teams mobile in the following format, and sends the auth code with the session ID back to Teams.
```
return res.redirect(`msteams://teams.microsoft.com/l/auth-callback?authId=${state.authId}&result=${req.query.code}`)
```
Teams calls success callback and sends result.

Teams calls the success callback and sends the result (auth code) to the 3P app. The 3P app receives the code in the success callback and use the code to retrieve the token, then the user information and update the user interface.
```
successCallback: function (result) { 
… 
} 
```

Use external OAuth providers

Add authentication to external browsers

Example

Example

See also

Feedback