はじめての Zoom API - OAuth編

■ 前置き

Zoomでは、Web管理画面やクライアント・アプリへZoomユーザのメールアドレス、パスワードでサインインすることで様々な機能をご利用いただくことができます。 一方、サードパーティ製のWebサービスからZoomユーザに代行して同等の処理をAPI経由で実施いただくことも可能です。 この「代行」処理を実現するための認証を強固に担うためZoomではOAuthを利用した連携をご用意しています。 ZoomでのOAuthは、ユーザのサインイン認証はZoom側で担いサードパーティ製のWebサービスへはAPIリクエストで必要となる「access_token」を発行することで実現しています。 以下、OAuth経由でAPIリクエストで必要となる「access_token」の取得方法についてご案内を進めたいと思います。

■ OAuthの大まかな流れ

以下図解で説明していきます。
サードパーティ製のWebサービスを「Provider A」、エンドユーザを「User A」としています。

補足）以下に記している「Publishable URL」、「Testable Url」、「Add URL」、「Client ID/Secret」については後述の「Marketplaceへの登録について」にてご確認いただけます。

1. 「User A」は「Provider A」で提供された「Publishable URL」（もしくは「Testable Url」、「Add URL」）を元にOAuth認証を開始します。
   

2. 「User A」は、「Publishable URL」（もしくは「Testable Url」、「Add URL」）を元に、Zoom側への認証ページへ誘導されます。
   ここで、User A は、「Provider A」に自身のパスワードを共有することなくサインインします。
   

3. サインインが完了すると、Zoomから「Provider A」へ「User A」に紐付いた「Authorization Code」をリダイレクトします。
   

4. 「Provider A」は、この「Authorization Code」と「Client ID/Secret」を組み合わせてZoomへ「User A」の「access_token」を要求します。
   

5. 「Provider A」が「User A」の「access_token」を取得できたところでAPIリクエストを実行する準備が完了です。

• 発行される「access_token」の有効期間は１時間です。
• 同時に発行される「refresh_token」の有効期間は15年です。
• 「access_token」が失効した場合は、「refresh_token」を利用して「access_token」の再発行ができます。
• 「access_token」を発行（もしくは再発行）されたとくは必ず「refresh_token」もデータベース等に保管して利用できる状態にしておくことを推奨します。
  

■ Marketplaceへの登録について

OAuthを利用するためには、事前にMarketplaceでの登録が必要となります。

1. 「https://marketplace.zoom.us」へサインイン(Sign in)します。
   

2. 「Develop」 > 「Build App」から登録画面に進みます。
   

3. 「OAuth」 > 「Create」をクリックして登録を進めます。
   

4. 登録後の識別のため任意の名称を「App Name」に入力します。
   利用するOAuthを管理者ユーザ専用にする場合は、「Account level app」を選択、
   管理者を含む全ユーザの許容を含める場合は「User-managed app」を選択します。
   また、OAuthの実装を自身のアカウント配下に所属しない外部ユーザへも展開を前提とする場合は「Would you like to publish this app to Zoom App Marketplace?」を有効にします。
   今回は、「App Name」を「OAuth Sample」、「User-managed app」とし、アカウント内のユーザへのみ利用を前提に「Create」をクリックします。
   

5. 「access_token」を取得する際に「Authorization」の生成で必要となる「Client ID」、「Client Secret」を控えます。
   「Redirect URL for OAuth」へサービス提供側でリダイレクト処理を受けるURLを入力します。
   「Add allow list」へZoom側へリダイレクトの際に送信元となり得るURLを記入します。（複数登録いただけます）
   

6. 次に最低限必要となる中の「Short description」、「Long description」を入力します。
   

7. 続いて同様に「Name」、「Email address」を入力します。
   *OAuthに関わる重要な周知事項が発生した際にはZoomから「Email address」へ通知されますので必ず存在する値を入力ください。
   

8. OAuthを経て取得された「access_token」で利用できる範囲を「Scope」で指定します。
   
   今回は、ユーザ自身の情報を許容できるよう「User」 > 「View user info」にチェックを入れ「Done」で閉じます。
   
   

9. サービス提供側から「Add Url」をユーザに提供することでZoomとのOAuth連携を開始いただけます。
   

■ 実装について

上記で解説した仕様をWebサービスの中で実装いただく必要がございます。

Nodeでの実装サンプル：
https://github.com/ysawamura-zoom/Workshop/tree/main/OAuth
https://github.com/zoom/zoom-oauth-sample-app

OAuthの実装について：https://marketplace.zoom.us/docs/guides/auth/oauth

OAuthで取得した「access_token」はhttpのヘッダー「Authorization」に「Bearer」として指定いただくことでAPIリクエストを実行いただけます。
APIについては以下より開示しており、OpenAPI(Swagger)へも対応しております。
　https://marketplace.zoom.us/docs/api-reference/zoom-api/methods/

■注意事項

サードパーティ製のWebサービスで実装される各種リダイレクトurl、「Client ID/Secret」は、サービス提供側のZoomアカウントでMarketplaceより発行されたものをご利用ください。 上記を含めパスワードなどをエンドユーザに求めることは第三利用の不正に繋がり規約違反として双方のサービス停止に発展する恐れがございますので必ずご注意ください。 サービス提供側で登録利用しているZoomアカウント(テナント)以外のZoomユーザを対象とする場合は必ずMarketplaceでの申請承認プロセスを完了させ「Publishable URL」が開示可能な状態である必要がございます。

Marketplaceでの開示方法について：　https://marketplace.zoom.us/docs/guides/publishing