title | description | ms.topic | ms.localizationpriority | ms.date |
---|---|---|---|---|
Support Third Party OAuth Providers |
Learn how to use external OAuth providers, add authentication to external browsers, and about the authenticate API parameters. |
how-to |
high |
09/01/2022 |
[!INCLUDE sdk-include]
You can support external or third-party OAuth providers, such as Google, GitHub, LinkedIn, and Facebook using the updated authenticate()
API:
function authenticate(authenticateParameters: AuthenticatePopUpParameters): Promise<string>
Add the following values to the authenticate()
API to support external OAuth providers:
isExternal
parameter- Three placeholder values in the existing
url
parameter
The following table provides the list of authenticate()
API parameters (AuthenticatePopUpParameters
) 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. |
height |
The preferred height for the pop-up. The value can be ignored if outside the acceptable bounds. |
url |
The URL of third-party app server for the authentication pop-up, with the following three parameter placeholders: - oauthRedirectMethod : Pass placeholder in {} . The Teams platform replaces this placeholder with a deep link or webpage, which updates the app server if the call comes from a mobile platform.- authId : UUID (Universal unique identifer) replaces this placeholder. The app server uses it to maintain the session.- hostRedirectUrl : pass placeholder in {} . The current platform and client replace this placeholder with a redirect URL, which redirects the user to the correct client after completing authentication. |
width |
The preferred width for the pop-up. The value can be ignored if outside the acceptable bounds. |
Note
The authID
parameter is valid for the duration of the auth session, which has a default timeout of 120 seconds.
For more information on parameters, see authenticate (AuthenticatePopUpParameters) function.
The following image provides the flow to add authentication to external browsers:
:::image type="content" source="../../../assets/images/tabs/tabs-authenticate-OAuth.PNG" alt-text="authenticate-OAuth":::
To add authentication to external browsers
-
Initiate the external auth-login process. The third-party app calls the TeamsJS function
authentication.authenticate
withisExternal
set as true to initiate the external auth-login process.The passed
url
contains placeholders for{authId}
,{oauthRedirectMethod}
, and{hostRedirectUrl}
.authentication.authenticate({ url: `${window.location.origin}/auth-start?oauthRedirectMethod={oauthRedirectMethod}&authId={authId}&hostRedirectUrl={hostRedirectUrl}&googleId=${googleId}`, isExternal: true }).then((result) => { this.getGoogleServerSideToken(result); }).catch((reason) => { console.log("failed" + reason); reject(reason); })
-
The Teams clients open the URL in an external browser after automatically replacing the placeholders for
oauthRedirectMethod
,authId
, andhostRedirectUrl
with suitable values.Example
https://3p.app.server/auth?oauthRedirectMethod=deeplink&authId=1234567890&hostRedirectUrl=msteams://teams.microsoft.com/l/auth-callback?authId=1234567890&result={result}
-
The third-party app server responds. The third-party app server receives and saves the
url
with the following three query parameters:Parameter Description oauthRedirectMethod
Indicates how the third-party app must send the response of authentication request back to the client, with one of the two values: deep link or page. authId
The request-id Teams creates for this specific authentication request that needs to be sent back to the client through a deep link. hostRedirectUrl
The deep link includes the URL schema of the initiating client to redirect after the authentication. [!TIP] The app can marshal
authId
,oauthRedirectMethod
, andhostRedirectUrl
in the OAuthstate
query parameter while generating the login URL for the OAuthProvider. Thestate
contains the passedauthId
,oauthRedirectMethod
, andhostRedirectUrl
, when OAuthProvider redirects to the server and the app uses the values for sending authentication response back to the initiating client as described in step 6. -
The third-party app server redirects to specified
url
. The third-party app server redirects to OAuth providers auth page in the external browser. Theredirect_uri
is a dedicated route on the app server. You can registerredirect_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":"…","hostRedirectUrl":"_"}&client_id=… &response_type=code&access_type=offline&scope= …
-
Sign in to external browser. The OAuth providers redirect back to the
redirect_uri
with the auth code and the state object. -
The third-party 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 deep link or through web page that callsnotifySuccess()
.if (state.oauthRedirectMethod === 'deeplink') { const clientRedirectUrl: string = state.hostRedirectUrl.replace('{result}', req.query.code) return res.redirect(clientRedirectUrl) } else { // continue redirecting to a web-page that will call notifySuccess() – usually this method is used in Teams-Web …
For example, in Teams mobile client, the modified
hostRedirectUrl
results the following:return res.redirect(`msteams://teams.microsoft.com/l/auth-callback?authId=${state.authId}&result=${req.query.code}`)
The provided value of
hostRedirectUrl
depends on the client that initiates the external authentication flow. -
Teams calls the success callback and sends the result (auth code) to the third-party app. The app receives the code in the success callback and uses the code to retrieve the token, then the user information and update the user interface.
successCallback: function (result) { … }