〜OAuth・CCG・管理者権限まわりで調べたこと〜
エグゼクティブサマリ
Box API/SDKを利用する場合、無料プランではOAuth 2.0により最小限の連携確認ができる認証・認可構成を構築でき、有料プランではCCG(Client Credentials Grant)により、定期実行が必要な業務にも強い認証・認可構成を構築できることが分かった。
背景
Box上に保管されているファイルを、DatabricksなどのデータプラットフォームからBox API/SDK経由で取り込みたいというニーズがあり、その実現方法を調査した。
Box APIには複数の認証方式が用意されているが、公式ドキュメントを読んだだけでは「どの認証方式を選べばよいか」「プランによって何が変わるのか」が分かりづらかった。特に、無料プランでも一部の認証方式は利用できるものの、実際に業務で継続的に使えるかどうかは別の話であり、この違いを事前に把握しておかないと手戻りが発生しかねないと感じた。
そこでまず、無料プランと有料プラン(Business以上)それぞれで「何ができて、何ができないのか」「利用する上でどのような前提条件があるのか」を整理することにした。
課題認識
調査を始めた当初、以下の点が分かりづらいと感じていた。
- OAuth 2.0とCCG(Client Credentials Grant)という2つの認証方式が存在するが、どちらがどのプランで使えるのか、公式ドキュメント上で一覧化されていない
- 無料プランのOAuth 2.0(開発者アクセストークン)がどの程度の用途に耐えられるのか(検証用なのか、本番でも使えるのか)が明記されていない
- CCGを有効化する際の操作(開発者コンソールでの承認送信、管理者コンソールでの認可)について、実際に手を動かさないと分からない部分が多い
そして、実際に検証を進めていく中で、当初は想定していなかった次の課題が見えてきた。
- プランがBusiness以上であっても、コラボレーターとして招待されただけのユーザーはCCGの承認送信ができない、というようにプランの契約状況と個々のユーザー権限が絡み合っている
この4点目は、「プランさえ上げればCCGが使えるようになる」という単純な話ではなく、「誰がその操作を行うか」という権限設計まで踏み込んで初めて見えてくる制約だった。
調査してわかったこと① 認証方式の違い(OAuth vs CCG)
Box API/SDKを利用する際の認証方式について調べたところ、大きく分けて次の2つが選択肢になることが分かった。
OAuth 2.0(開発者アクセストークン)
- 無料プランでも利用可能
- 必要な情報は、クライアントID、クライアントシークレット、開発者アクセストークンの3つ
- 開発者アクセストークンは60分で失効し、かつ更新(リフレッシュ)ができない
- Box公式のドキュメント上でも、開発者アクセストークンはあくまで動作検証・自分自身のアカウントでのテスト用途に向いたものであり、本番運用には適さないとされている
今回の環境では、実際にこの開発者アクセストークンを使ってBox APIを呼び出す検証を行った。60分ごとにトークンを再発行する必要があるため、継続的なジョブとして組み込むには不向きだと分かった。
CCG(Client Credentials Grant)
- Business以上のプランで利用可能
- 必要な情報は、クライアントID、クライアントシークレット、エンタープライズIDの3つ
- 特定のユーザーとしてではなく、サービスアカウントという専用のプログラム上のユーザーを介して認証・認可が行われる
- サービスアカウントは、管理者が管理コンソールでCCGアプリケーションを承認した時点で自動的に生成されるもので、開発者が手動で作成するものではない(Box公式ドキュメントより)
- 個人のBoxアカウントに紐づかないため、担当者の異動・退職の影響を受けにくく、サーバー間の自動化統合に適した仕組みになっている
- アプリケーション単位での認証となるため、OAuth 2.0のようなトークンの頻繁な更新が不要
私はこの結果から、「無料プランのOAuth 2.0は、Box API/SDKで実現したいことができそうか試すための検証手段」「業務でデータを継続的に取り込むならCCGが前提になる」と判断した。
Box公式ドキュメント上では、CCGアプリが承認されると、Box Enterprise内に自動的にサービスアカウント(専用のメールアドレスを持つプログラム上のユーザー)が作成されるとされている。ただし、今回の検証では、顧客側に確認を依頼したところ、該当するようなメールアドレスを持つユーザーの存在は確認できなかったとの回答を得ている。ドキュメントの記載と実際の見え方に差異がある可能性があるため、この点は断定せず、利用環境ごとに確認することをおすすめしたい。
調査してわかったこと② プランと権限の関係
CCGを使えるようにするには、プランがBusiness以上であることに加えて、実際に操作する人の権限も関係することが分かった。
CCGを有効化するには、次の2ステップが必要である。
- 開発者コンソールで、作成したアプリの認証・認可を送信する
- 管理者コンソールで、その申請を認可する
ここで気づいたのは、Business以上のプランを契約しているBoxであっても、そこにコラボレーターとして招待されたユーザーは、上記の申請(1)を送信することも、認可(2)を行うこともできないという点である。申請の送信・認可のいずれも、管理者コンソールに遷移できる権限を持つユーザーでなければ実行できない。
つまり、「プランをBusiness以上にすればCCGが使えるようになる」という単純な話ではなく、「誰がBoxの管理者権限を持っているか」まで確認しないと、CCGを有効化する作業自体が進められない、ということになる。この点は、プラン変更を検討する際に見落とされやすいポイントだと感じた。
検証(Databricksとの連携)
実際に、CCGで取得した認証情報を使ってBox APIを呼び出し、Databricks側にデータを取り込めるかを検証した。
なお、本記事では実際の業務アーキテクチャをそのまま公開することは避け、検証MVPレベルの構成として紹介する。
- CCGでクライアントID・クライアントシークレット・エンタープライズIDを用いてアクセストークンを取得
- 取得したトークンを使ってBox APIを呼び出し、対象ファイルを取得
- Databricks側のNotebookから呼び出し、Databricksのボリュームにデータを書き込み
この検証を通じて、無料プランのOAuth 2.0(開発者アクセストークン)では60分ごとの再認証が必要になるため、Databricks側でジョブとして定期実行する構成には向かないことを改めて確認した。CCGであれば、サービスアカウント経由でアプリ単位の認証が継続するため、ジョブへの組み込みを前提とした構成に適していると考えている。
本検証はあくまでMVP(実現可能性の確認)レベルのものであり、実際の本番運用でのジョブ構成・エラーハンドリング・スケーリングなどは別途検討が必要である。
得られた示唆
今回の調査・検証を通じて、以下の示唆が得られた。
- Box API/SDKで継続的なデータ連携を行いたい場合、無料プランのOAuth 2.0はあくまで動作検証用と割り切り、本番運用にはBusiness以上のプランとCCGを前提に検討すべきである
- CCGを有効化するプロセス(開発者コンソールでの承認送信→管理者コンソールでの認可)は、プランの契約状況だけでなく、実際に操作するユーザーの権限にも左右される。招待されたコラボレーターだけではこの作業を完結できないため、事前に「誰が管理者権限を持っているか」を確認しておく必要がある
- CCGのクライアントID・クライアントシークレット・エンタープライズIDは、これらの情報を知っていれば誰でも認証できてしまうため、共有時は閉じた環境で行い、共有後は速やかに削除するなどの運用ルールを設けたほうがよい。もちろん、情報を扱う人間側のリテラシーも同時に求められる
- Box公式ドキュメントの記載(サービスアカウントの自動生成など)と、実際の見え方に差異が生じるケースもあるため、公式ドキュメントの記載を鵜呑みにせず、自身の環境で実際に確認する姿勢が重要である
まとめ
Box API/SDKを使ってDatabricksと連携しようとしたとき、認証方式(OAuth vs CCG)やプラン・権限による制約が分かりづらく、公式ドキュメントだけでは全体像を掴みにくかった。
今回の調査を通じて、無料プランのOAuth 2.0はあくまで検証用途に留まり、業務でのデータ連携にはBusiness以上のプランとCCGが前提になること、そしてCCGの有効化には管理者権限を持つユーザーの関与が不可欠であることが分かった。
Box API/SDKを使ってシステム連携を検討している方の参考になれば幸いである。