はじめての Zoom API - Server-to-server OAuth編

<h2>■ 前置き</h2>
Server to Server OAuth App では、Zoom API を利用する際に必要となるアクセス・トークンの生成に必要な各種 ID, Secret を提供管理し、それら情報をもってトークンを生成いただけます。
また、ユーザー認証を必要とするOAuthアプリとは異なりユーザごとのブラウザ認証を必要としません。
ユーザごとのOAuth認証については<a href="https://qiita.com/yosuke-sawamura/items/514e791afb4cb02fd956" target="_blank">はじめての Zoom API - OAuth編</a>を参照ください。<br>

<h5>Server to Server OAuth App の特徴</h5>
* オーナー権限でのAPIアクセスを許容するアクセス・トークンの生成<br>
* 生成されたトークンの有効時間は1時間<br>
* Refresh(更新)トークンはない<br>
* 再発行すると以前のトークンは失効<br>
* 非アクティブ化されると、生成済みトークンは失効<br>
* 利用できるスコープ(利用範囲)の制限<br>
* Server to Server OAuth App 登録の削除は可能<br>
<br>

<font color="red">**注意)**</font> Server to Server OAuth App (及び旧 JWT App) で生成いただけるアクセス・トークンは管理者のユーザID、パスワードと同じ権限を持っています。
自社で開発したプラットフォームへユーザから以下説明にある「ID、Secret」や生成後のトークンを共有いただく実装は個人情報の収集と同等にあたり、<font color="red">規約に反して</font>しまいます。別途OAuthを含むMarketplaceでの申請承認もしくは別途ISV契約をご検討ください。
Server to Server OAuth App (及び旧 JWT App)は社内利用(Internal usage)でのみの許容となります。

<b>Zoomサービス規約</b>
日本語 : https://explore.zoom.us/ja/terms/ (3. a 登録情報)
英語 : https://explore.zoom.us/en/terms/ (3. a Registration Information.)

<b>Zoom API ライセンスおよび利用規約</b>
日本語 : https://explore.zoom.us/ja/legal/zoom-api-license-and-tou/ (6. サードパーティによる利用)
英語 : https://zoom.us/docs/en-us/zoom_api_license_and_tou.html (6. Third Party Use)

<h2>■ Marketplaceへの登録について</h2>

1. 前段としてhttps://marketplace.zoom.us へサインインしての登録が必要となりますが、サインインするユーザ（メールアドレス）がテナントのオーナー以外の場合は権限付与をする必要があります。
一旦、オーナー権限のユーザ（メールアドレス）で http://zoom.us へサインインし、「管理者 > 役割」よりアクセス権限を確認し必要に応じて「サーバー間 OAuth アプリ」(Server-to-server OAuth App)にチェックを入れて「設定を保存」で有効にします。

![スクリーンショット 2022-06-07 8.44.15.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2123842/5600b2f5-d366-2319-a769-e8dfedf9a599.png)
![スクリーンショット 2022-06-07 8.44.35.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2123842/8ca52e6b-ac14-a2c6-787e-592127a0d244.png)

https://marketplace.zoom.us/ へ権限付与をされたユーザ(メールアドレス)でサインインし、右上プルダウン「Build App」より遷移します。
![スクリーンショット 2022-06-07 8.51.37.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2123842/7c4dc1a5-90cc-b3ae-0e1c-9515ec221c3f.png)

画面右下に「Server-to-server OAuth」枠の下「Create」で登録を進めます。
![スクリーンショット 2022-06-07 8.53.06.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2123842/a35170d4-5f90-09bd-d5d8-3a6fa8d63301.png)

 「App Name」に登録名を指定します。ここでは「Sample Server to Server App」と指定しています。「Create」で進みます。
![スクリーンショット 2022-06-07 8.55.01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2123842/827a14c9-2c88-cbab-1988-9680b286a0ae.png)

最初に現れる画面上の「Account ID」、「Client ID」、「Client secret」は後ほどトークンを生成する際に必要になりますので控えておきます。右下「Continue」で進みます。
![スクリーンショット 2022-06-07 8.55.46.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2123842/6e4d2b99-7ab7-cebe-0431-2d07ee9500f0.png)

ユーザ情報となる「Name」と「Email address」を入力して「Continue」で進みます。
＊重要な変更事項や通知をメールアドレス宛に送付される場合に使用されるため利用可能なメールアドレスを指定ください。
![スクリーンショット 2022-06-07 8.59.28.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2123842/fbf9b1b1-113b-88c2-b1d2-ee7f8d3962fc.png)

「Event subscription」はWebHook通知機能を有効にするための設定です。ここでは割愛し「Continue」で進みます。
![スクリーンショット 2022-06-07 9.02.34.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2123842/1dd6e4aa-e197-510f-bfda-9b932cb0eb7f.png)

「Scopes」ではトークンでアクセスできるAPIの範囲を指定します。ここでは、ユーザ情報をのみへのアクセスを許容するように指定しています。
![スクリーンショット 2022-06-07 9.04.01.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2123842/3d197f30-f48a-04db-9f5d-dd17a2801790.png)
![スクリーンショット 2022-06-07 9.04.35.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2123842/c6c5cf9f-6e95-0856-f447-5dd8016be47d.png)

最後に「Active your App」をクリックして有効にします。
![スクリーンショット 2022-06-07 9.06.57.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2123842/a0de9585-faae-225b-4968-660e1c61cc2c.png)

<h2>■ トークン生成方法について</h2>
トークンはBase64でエンコードされた「CliendID:ClientSecret」と「AccountID」を指定してZoom側にHTTP越しにPOSTリクエストすることで生成します。

◆Curlでの例
*Base64でのエンコード結果は<a href="https://www.base64encode.org/">BASE64</a>などで別途取得する必要があります。
```shell
$ curl --request POST --url 'https://zoom.us/oauth/token?grant_type=account_credentials&account_id=<Account ID>' \
--header 'Authorization: Basic <Base64Encode(ClientID:ClientSecret)>' 
```

◆Nodeでの例
```javascript
 var accountid = <Account ID>;
 var clientid = <Client ID>;
 var clientsecret = <Client Secret>;
 var basenc = Buffer.from(clientid + ":" + clientsecret).toString('base64');
 var token = await getToken(accountid,basenc);

 async function getToken(accountid,basenc){
  return new Promise(function (resolve, reject) {
    request({
          url: "https://zoom.us/oauth/token?grant_type=account_credentials&account_id="+ accountid,
          method: "POST",
          headers: {
              'Authorization': 'Basic ' + basenc
          }
      }, async function(error, response, body) {
          if (error) {
              console.log(error);
              reject(error)
          } else {
              var obj = JSON.parse(body);
              const data = obj.access_token;
              resolve(data);
          }
      });
    });
 };

```

<h2>■ トークンを利用したAPIリクエストについて</h2>
HTTP経由のRestAPI形式でリクエストいただけます。
もちろんCurl等のコマンドラインツールを用いて簡易的に確認いただくことも可能です。

以下アカウントオーナー自身の情報を取得する例となります。
```shell
$ A=$(echo -n '<Client ID>:<Client secret>' | base64); \
token=$(curl -s --request POST --url 'https://zoom.us/oauth/token?grant_type=account_credentials&account_id=<Account ID>' \
--header 'Authorization: Basic '$A \
|  awk -F\" '/"access_token"/{print $4}'); \
curl -s --request GET --url 'https://api.zoom.us/v2/users/me' \
--header 'Authorization: Bearer '$token \
| python -m json.tool
```

Node.js でのサンプルは下記よりご参考にしていただけます。
　<a href="https://github.com/ysawamura-zoom/Workshop/tree/main/Server-to-server-OAuth" target=_blank>Server to Server OAuth - app.js</a>
　<a href="https://github.com/zoom/zoom-api-jwt" target=_blank>Sample Node app using jsonwebtoken</a>


その他、ご利用いただけるAPIについては以下より開示しており、OpenAPI(Swagger)へも対応しております。
　<a href="https://marketplace.zoom.us/docs/api-reference/zoom-api/methods/" target=_blank>https://marketplace.zoom.us/docs/api-reference/zoom-api/methods/</a>


<h2>■ 補足事項</h2>

その他、Server-to-server OAuthについては下記を参照ください。
<a href="https://marketplace.zoom.us/docs/guides/build/server-to-server-oauth-app" target=_blank>Server-to-server OAuth</a>

JWT Appsは2023年6月に廃止を予定しています。Server-to-server OAuthの利用もしくはOAuthでの実装を推奨します。その他、開示事項については下記を参照ください。
<a href="https://marketplace.zoom.us/docs/guides/build/jwt-app/jwt-faq" target=_bank>JWT App Type Deprecation FAQ<a>

Postmanを利用した参考資料
https://jenzushsu.medium.com/setting-up-server-to-server-s2s-oauth-to-test-zoom-apis-via-postman-32c9cd7a73