2021年7月23日 星期五

[zoom, jwt] How to create a Windows Zoom Client App

How to create a Windows Zoom Client App

井民全, Jing, mqjing@gmail.com



In this document, I'll show you how to create an app token for your Zoom client app using JWT.IO website. In order to prevent the mistakes, a C# module that can generate JSON Web Token (JWT) for your Zoom Client App's App Token by giving SDK key and SDK secret are also included. How to validate the generated JWT token? You can directly paste the token to JWT.IO debug website. Check detail in the following.


Concept

Zoom Client SDK requires an App Token for authenticating to use the SDK. If you want to write the Zoom Client App, at first, you should generate the App Token. With the App token, the App gets access to the Zoom Client SDK.

Zoom chooses JSON Web Token (JWT) standard to represent the App token. Ok, let's create the JSON Web Token for your app token. 


In this document, I'll show how to create a JSON Web Token by giving the SDK key and the SDK secret from JWT.IO website. If you follow the procedure of the Zoom official document, you'll found it's easy to make mistakes that cause your application hangs or always get authorized failure because of the wrong JSON Web Token format. 


Thanks, Mr. k.krylov[6], a C# module can automatically generate JSON Web Token for your Zoom Client App's App Token by giving SDK key and SDK secret. Using the module, you'll always easily and make no mistakes to generate the JSON Web Token for your application. I modify the code to fill the format of the ZOOM Client SDK authentication.  NOTE: never hardcode your SDK Key or Secret in your application or anywhere that is publicly accessible.


Github: Source

Table of Content

Concept 1

1. The SDK key and the SDK Secret 2

2. Generate JSON Web Token 3

2.1. Generate JWT token (using JWT.IO) 3

2.2. Generate JWT token (in C#) 5

2.2.1. Code 6

2.2.2. Usage 7

2.2.3. Debug 7

3. Create the Windows Zoom Client App 8

4. Troubleshooting tips 12

5. References 12





1. The SDK key and the SDK Secret

Based on the Client SDK, a Zoom client app authenticates with Zoom through a pair of credentials, SDK key, and the SDK secret that were signed and communicate using JSON Web Tokens. 

In order to use Zoom Client SDK, you need the SDK key and the SDK secret to generate a JSON web token for authenticating with Zoom. Here, I'll show you how to get these credentials.

Step 1: Sign-in to the Zoom App Market

https://marketplace.zoom.us/


Step 2: Choose SDK

(Edit)

2. Generate JSON Web Token

The JSON Web Token (JWT) is used for authenticating to access the Zoom Client SDK. We can use JWT.IO to generate the token by hand. Here is a comprehensive tutorial [3]. 

If you want to avoid mistakes from generating JWT token by yourself. You can use Microsoft.IdentityModel.Tokens package to auto-generate JWT token for you. In order to make sure the token is correct, you can paste the token and the secret to the JWT.IO debugger to see the decoded metadata.


2.1. Generate JWT token (using JWT.IO)

Step 1: The JWT.Io site

https://jwt.io/


Step 2: Fill the form

Header

{

  "alg": "HS256",

  "typ": "JWT"

}


Payload

For generating epoch time, using Tool: Generate Epoch time, Here, appKey use the SDK key that is generated from https://marketplace.zoom.us/.

{

  "appKey": "1234567890",                  // SDK key

  "iat": 1627021788,                            //  The time when the JWT is issued. 

  "exp": 1627025388,                          // JWT expires time (in Epoch format). Iat + 3600 sec

  "tokenExp": 1627025388                 // Session expires time  (in Epoch format): iat + 3600 sec

}

Based on the document, the parameters are listed as follows. 

  • appKey: the SDK Key found in the App Dashboard.

  • iat: the timestamp of the token in seconds identifying when the JWT is issued.

  • exp: when the JWT itself expires in epoch format. Must be at least 30 minutes (1800 seconds) greater than the token’s iat field. Max value of iat value + 48 hours (172,800 seconds).

  • tokenExp: when the SDK authentication session expires in epoch format. Must be at least 30 minutes (1800 seconds) greater than the token’s iat field. 



Verify Signature


Fill the 'Your_SDK_SECRET' from https://marketplace.zoom.us/.


HMACSHA256(

    base64UrlEncode(header) + "." +

    base64UrlEncode(payload),

    Your_SDK_SECRET)


Example

(Edit)


2.2. Generate JWT token (in C#)

You can use the following c# code to generate the JWT token. Mr. k.krylov[6] provided a valuable example to do the job. I modify the code for creating the Zoom Client JWT token. 


2.2.1. Code

File: class1.cs


// The code is modified from the address of: 

// https://devforum.zoom.us/t/how-to-create-jwt-token-using-rest-api-in-c/6620/20


using System;

using System.Text;

using System.IdentityModel.Tokens.Jwt;

using Microsoft.IdentityModel.Tokens;

namespace ZoomIntegration.Configuration

{


    public class ZoomToken

    {

        public ZoomToken(string ZoomApiKey, string ZoomApiSecret)

        {

            DateTime Expiry = DateTime.UtcNow.AddMinutes(5);

            string ApiKey = ZoomApiKey;

            string ApiSecret = ZoomApiSecret;


            //int ts = (int)(Expiry - new DateTime(1970, 1, 1)).TotalSeconds;

            // modify by Jing.

            DateTime now = DateTime.UtcNow;

            int ts = (int)(now - new DateTime(1970, 1, 1)).TotalSeconds;

           // end of modification


            // Create Security key  using private key above:

            // note that latest version of JWT using Microsoft namespace instead of System

            var securityKey = new Microsoft.IdentityModel.Tokens.SymmetricSecurityKey(Encoding.UTF8.GetBytes(ApiSecret));


            // Also note that securityKey length should be >256b

            // so you have to make sure that your private key has a proper length

            var credentials = new SigningCredentials(securityKey, SecurityAlgorithms.HmacSha256);


            //Finally create a Token

            var header = new JwtHeader(credentials);


            //Zoom Required Payload

            var payload = new JwtPayload

            {

                //{ "iss", ApiKey},

                //{ "exp", ts }

                

                // modify by Jing.

                {"appKey", ApiKey},

                {"iat", ts },

                {"exp", ts + 3600},

                {"tokenExp", ts + 3600}

                // end of modification

            };


            var secToken = new JwtSecurityToken(header, payload);

            var handler = new JwtSecurityTokenHandler();


            // Token to String so you can use it in your client

            var tokenString = handler.WriteToken(secToken);

            //string Token = tokenString;

            this.Token = tokenString;

            Console.WriteLine("token = " + tokenString);

        }


        public string Token { get; set; }

    }


}


2.2.2. Usage

            string apiKey = "YOUR_SDK_KEY";

            string apiSecret = "YOUR_SDK_SECRET";

            ZoomToken myToken = new ZoomToken(apiKey, apiSecret);

            param.jwt_token = myToken.Token;

            Console.WriteLine("token = " + param.jwt_token);

        




2.2.3. Debug

Step 1: Paste the generated JWT token to the JWT.Io

Address: https://jwt.io/


2.2.4. Source

  1. Github: Source

3. Create the Windows Zoom Client App

Here is only 4 steps to building up your Windows Zoom Client App. For detailed information, you can check the Zoom Client SDK document[7].

Step 1: Download the C# Wrap Zoom Client SDK

 https://marketplace.zoom.us/docs/sdk/native-sdks/windows/c-sharp-wrapper


Step 2: Open the Projoect

File: zoom_sdk_c_sharp_wrap.sln

Step 3: Change the Startup project as zoom_sdk_demo


Step 4: Setup the Configure as Release and x86 and Run

Currently, the SDK only supports the Release mode and x86 platform [ref].

(Edit)

Past the JWT Token to the App Token


4. Troubleshooting tips

  1. In trouble on application hangs after input the App token?

    1. The issue is usually caused by wrong metadata in the payload in the JWT, such as

      • missing the required fields,

      • wrong value setup for the metadata of iat, tokenExp or exp,

      • another wrong value case is too short expired duration, in general, for testing, we can set the expired duration in 1 day,

      • and more[4].

5. References

  1. The SDK Home, https://developers.zoom.us/

  2. Essential guides, https://marketplace.zoom.us/docs/sdk/video/windows/essential

  3. How to create a sample JWT for the Client SDK, https://zoomdevelopersupport.zendesk.com/hc/en-us/articles/360056168291-How-to-create-a-sample-JWT-for-the-Client-SDK

  4. I’m getting an invalid Token, https://marketplace.zoom.us/docs/sdk/native-sdks/auth/troubleshoot#im-getting-an-invalid-token

  5. https://jwt.io/

  6. A C# class module for generating JWT token, https://devforum.zoom.us/t/how-to-create-jwt-token-using-rest-api-in-c/6620/20

  7. The Client SDK Document, https://marketplace.zoom.us/docs/sdk/native-sdks/introduction

  8. Audio control, https://marketplace.zoom.us/docs/sdk/video/web/essential/video

  9. Zoom SDK, Authentication, https://marketplace.zoom.us/docs/sdk/native-sdks/auth

  10. Windows SDK, https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk/

  11. C# Wrap, https://marketplace.zoom.us/docs/sdk/native-sdks/windows/c-sharp-wrapper

  12. https://jwt.io/#libraries-io





at