Architecture

Architect your Zoom App to have a front-end that displays the WebView of your web application containing any interactive components and data that are useful to the user and a backend that can at minimum handle user authorization, Zoom API calls, app launch and page redirects.

This document provides details on the different processes that your app’s backend must support.

OWASP secure headers for app home URL and html

The Open Web Application Security Project (OWASP) recommends a set of https headers for web applications that increase security and reduce browser vulnerability to attack. For more information, including specific guidance and tools, see OWASP.

The Zoom Apps platform enforces a subset of the OWASP recommendations. The https MIME type text/html response from your server for the app’s home URL must be decorated with security headers recommended by the OWASP Secure Headers Project. The Zoom client validates all document (MIME type text/html) responses with a 200 status code for the presence of OWASP Secure Headers. Ensure that your app backend decorates its html responses with the following headers:

  • Strict-Transport-Security
  • X-Content-Type-Options
  • Content-Security-Policy
  • Referrer-Policy

See OWASP Secure Headers for App Home URL and HTML.

Requests originating from the Zoom Client

The Zoom Client includes an OS-agnostic User-Agent header in requests it originates. This header will be as follows regardless of the environment in which the client originating the request is installed.

Mozilla/5.0 ZoomWebKit/537.36 (KHTML, like Gecko) ZoomApps/1.0

App installation

Zoom Apps can be installed in one of these three ways:

  • Local installation using the Local Test feature found in your Marketplace app configuration. This is made available to you for testing purposes.

  • From the Marketplace app listing page.

  • From the Zoom Apps listing page in the Zoom client.

To provision installation from the Marketplace and the Zoom client, you are required to provide a direct landing url in your App configuration page.

Once your app is published on the Zoom App Marketplace, a ‘Visit Site to Install’ button is included on your app listing page. When users click this button, they will be taken to your Direct landing URL.

This endpoint provides a way for you to intercept the request before prompting your user to login or authorize the Zoom App. It is a good opportunity for you to generate an OAuth 2.0 state parameter to use in your app's OAuth flow.

Authorization (OAuth redirect)

From your direct landing page, request the user to authorize your app. If the user chooses to authorize, Zoom will redirect the user to your app's redirect URL, along with the original state parameter and an authorization code that can be exchanged with user's OAuth token. After receiving the token, use it to generate a deep link as shown below. Optionally, you may store it in a database or cache for later use if your app will be making requests to Zoom Restful APIs on behalf of the user.

After retrieving a valid access token, make a POST request to the deep link API on behalf of the user so that the app gets launched in the user’s Zoom client. Depending on where the app installation was initiated from (i.e. in a meeting or in the Apps panel), the Zoom client will open the app in the proper context.

POST /v2/zoomapp/deeplink/ HTTP/1.1
Host: https://api.zoom.us
Content-Type: application/json
Authorization: Bearer <access_token>

{"action": "go"}

Note that there is a 256 character limit on the action parameter.

After you receive a deep link, redirect the user to this link to launch the app in the user’s client.

App launch in the Zoom client

After redirecting the user to the deep link, the Zoom Client will attempt to launch your app’s home page by making a GET request to the Home URL that you entered in the Information tab of your Zoom App.

To validate that the incoming request is from Zoom and to retrieve data such as source of app usage(in a meeting or outside a meeting), user’s Zoom participant ID(uid) and meeting ID(if the app was opened during a meeting), your app must decrypt the context header of the request.

Third-party OAuth(optional)

In many cases, OAuth can be conducted within the Zoom Apps app in the client. This is the least complex approach. In some situations, users of an app may not want to enter their credentials directly in and app and some OAuth providers do not allow user agents that are not standalone browsers. In that instance, the OAuth flow will need to involve an external browser.

Care must be taken when implementing OAuth in an external browser. The OAuth flow must finish in the same session that it began. The below is on example of how to implement OAuth that does this. It involves calling zoomSDK.openURL to begin the authorization flow which returns the authorization_code using the API endpointhttps://api.zoom.us/v2/zoomapp/deeplink. The deeplink causes the browser to open the app and pass the authorization_code back.

The implementation details may vary depending on the provider you use. The diagram below provides a basic overview how this works:

3rd-party OAuth Diagram

The steps shown in the above diagram are described below:

  • When the app first connects to the backend, create a session identifier and put it in a cookie.

  • When the app backend wants to start third party OAuth (possibly because a user requests it or possibly as the first step in app launch), this following sequence begins.

  • (1) Generate a state-nonce that can be used to lookup the Zoom user_id in step (6) and a PKCE code_verifier that will be used in step (11)

  • (2,3) Open the authorization GET request in the browser.

  • (4,5) Normal authorization code OAuth happens ending with the authorization code being sent to the auth_redirect URL.

  • (6) Use the state-nonce in the state parameter to lookup this user_id and retrieve the Zoom OAuth Token.

  • (7) Use the OAuth token to retrieve a deep link that will open an app for this user.

  • (8) Send the deeplink to the backend.

  • (9) The backend goes to the zoommtg:// schema.

  • (10) The browser opens the Zoom Client and the Zoom Client uses the payload to open the app.

  • (11) The app is launched at its homepage with the auth_code and state-nonce embedded in the payload.

  • (12) Verify that the state-nonce is associated with this session identifier and lookup the PKCE token associated with this state-nonce.

  • (13) Do standard PKCE token acquisition from the backend.

Embedded browser versions

The OS of your machine that runs the Zoom client determines the browser engine that runs the embedded browser that renders Zoom Apps.

For Windows, it’s Microsoft Edge WebView2 (which uses Microsoft Edge (Chromium) as the rendering engine to display the web content in native apps) or CEF (Chromium Embedded Framework). 32-bit CEF has an absolute memory limit of 1.0 GB for Javascript. Less may be available to allocate if memory is fragmented. An allocation within Javascript of 512 MB should be achievable. 64-bit CEF has an absolute memory limit of 4.0GB for Javascript.

For Mac, it’s WKWebView, tied to the version that your Safari browser uses.

Need help?

If you're looking for help, try Developer Support or our Developer Forum. Priority support is also available with Premier Developer Support plans.