Authentication

Set up in-client OAuth for your Zoom App#

Use in-client OAuth to let users add your Zoom App and authorize its Zoom REST API scopes directly from the Zoom client. This eliminates the need to send users through a separate web-based authorization flow when adding or reauthorizing the app.

With in-client OAuth, you can:

• Let users add your app from the Zoom client.
• Get OAuth access tokens for the Zoom REST API.
• Prompt users to reauthorize the app when you add or change scopes.

Enable in-client OAuth feature#

Enable the In-client Oauth feature for your Zoom App Marketplace app.

1. Sign in to your developer account on the Zoom App Marketplace .
2. Select the Developers link in the lower left corner to open the Created Apps page. If you don't see the Created Apps page, verify that you have the correct permissions.
3. On the Created Apps page, select your app.
4. Select Features, and enable In-client OAuth.
5. Under OAuth allow list, add your app's Home URL.

Implement in-client OAuth#

The in-client OAuth flow uses the Zoom Apps SDK authorize method and onAuthorized event.

The flow works as follows:

1. Your app calls authorize. Zoom checks whether the user has already authorized the app's scopes.
   • If the scopes are already authorized, Zoom completes the authorization without prompting the user.
   • If the app has new or changed scopes, Zoom displays a consent screen and asks the user to reauthorize the app.
2. Your app receives an authorization code through the onAuthorized event.
3. Your application server exchanges the authorization code for a Zoom REST API access token.

1. Add the OAuth capabilities#

Add authorize and onAuthorized to the capabilities in your Zoom Apps SDK config call.

window.onload = function () {
    zoomSdk.config({
        capabilities: [
            'getRunningContext',
            'getSupportedJsApis',
            'openUrl',
            'authorize',
            'onAuthorized',
        ],
    });
};

2. Start the authorization flow#

Call authorize with:

• codeChallenge: A PKCE code challenge. Only the plain code challenge method is supported.
• state: An optional value that your app can use to maintain state and validate the authorization response.

zoomSdk
    .authorize({
        state: 'TIA5UgoMte',
        codeChallenge: 'lkjqwp4rt9uq03wr',
    })
    .then((ret) => {
        console.log(ret);
    })
    .catch((e) => {
        console.log(e);
    });

3. Receive the authorization code#

Register an onAuthorized event listener to receive the authorization code.

zoomSdk.addEventListener('onAuthorized', function (event) {
    console.log(event);

    $.post('/api/v1/auth/token', event, function (data, status) {
        console.log('Data ' + data, '\nStatus: ' + status);
    });
});

The event is triggered after Zoom checks the user's authorization status. Your app should send the authorization code to your application server.

4. Validate the state#

If you provide a state value when calling authorize, verify that the value returned in onAuthorized matches the value you originally provided.

This helps ensure that the authorization response belongs to the authorization request initiated by your app.

5. Exchange the authorization code for an access token#

From your application server, send a token request to Zoom using:

• The authorization code received from onAuthorized.
• The code_verifier used to generate the PKCE codeChallenge.

Zoom returns an access token that your application server can use to call the Zoom REST APIs.

Support existing web-based installations#

In-client OAuth does not replace the traditional Zoom Marketplace installation flow. Your app must continue to support users who install it through the Zoom Marketplace or your own installation pages.

When adding in-client OAuth to an existing app:

• Continue supporting your existing web-based installation flow.
• Move any installation logic that your app needs into your backend as necessary.
• Continue handling tasks such as creating application users, creating sessions, and storing OAuth tokens.
• Use the X-Zoom-App-Context header sent to your app's Home URL to identify the user and context when required.

For example, if your existing installation flow creates a user record and stores a Zoom OAuth token, make sure the in-client flow performs the equivalent backend operations.

Test in-client app installation#

The in-client installation flow isn't available for unpublished apps. You can use one of the following approaches to test the flow during development.

Test with one user#

Use this approach when you have only one Zoom user available.

1. Sign in to the Zoom App Marketplace and add your app to your account.
2. Open the Zoom client and start a meeting.
3. Open your app and send an app invitation to yourself.
4. Close the app without ending the meeting.
5. Return to the Zoom App Marketplace and remove the app from your account.
6. Return to the meeting.
7. Find the app invitation in the chat and accept it.
8. Verify that the in-client OAuth flow runs as expected.

Test with two users#

Use this approach when you have two Zoom accounts or Zoom client instances.

1. User 1: Sign in to the Zoom App Marketplace and add the app.
2. User 1: Open the Zoom client and start a meeting.
3. User 2: Join the meeting without adding the app.
4. User 1: Send User 2 an invitation to add the app.
5. User 2: Open the invitation from the chat and accept it.
6. Verify that the in-client OAuth flow runs as expected.

Support third-party OAuth#

If your app connects to a third-party service, you can usually complete that service's OAuth flow directly within your Zoom App.

Use an external browser instead when:

• Users shouldn't enter their credentials inside the app.
• The third-party OAuth provider doesn't support authentication from an embedded browser.
• The provider requires a standalone browser for authentication.

When you use an external browser, make sure the OAuth flow starts and finishes in the same user session.

Example implementation flow for third-party OAuth with an external browser#

This is an example of a typical third-party OAuth flow with an external browser.

1. When the app first connects to your backend, generate a session identifier and store it in a cookie.
2. When authentication is required, generate: a. A state-nonce to identify the Zoom user and session. b. A PKCE code_verifier.
3. Open the third-party authorization URL in the user's browser, and complete the third-party OAuth authorization flow: a. Receive the authorization code at your redirect URL. b. Use the state-nonce to identify the Zoom user and retrieve their Zoom OAuth token.
4. Use the Zoom OAuth token to generate a deep link that opens your app, and send the deep link to your backend.
5. Redirect the browser to the zoommtg:// URL.
6. When the Zoom client opens and launches your app, include the third-party authorization code and state-nonce in the app launch payload.
7. Verify that the state-nonce belongs to the current session and retrieve the associated PKCE information.
8. Exchange the third-party authorization code for an access token from your backend.

If the third-party authorization server doesn't support PKCE, you can omit PKCE from this flow.

Reduce authentication friction#

Make authentication as seamless as possible, especially when users join a meeting.

Consider the following practices:

• Authenticate users before meetings. Complete required authentication before the meeting starts when possible.
• Use Guest Mode for first-time users. Let users try your app during a meeting before requiring them to complete account authentication.
• Associate accounts with the Zoom user_id. Use the user_id to restore a user's session and avoid unnecessary authentication prompts.
• Avoid relying on cookies for Zoom App sessions. Cookies can be removed when users leave a meeting, which can cause users to authenticate again. Use the user_id from the app context header instead.
• Reuse existing browser authentication. If users are already signed in to your service in their system browser, use openUrl to authenticate through that existing browser session.
• Use the system browser for OAuth when required. Some authentication providers don't allow authentication from embedded browsers.
• Use embedded login forms only when appropriate. For services that support authentication within the Zoom client, you can provide your own login and password form.