Box Platformの基本: 認証方法の基礎
TL;DR — アプリがそのサービスへのアクセスに使用するBox Platformの認証方法 (OAuth 2.0、JWT、CCG、アプリトークン) について、実際の例を使って説明します。
アプリケーションがどのようにBox APIにアクセスするか疑問に思ったことはありませんか。そう思ったことがあるのはあなた一人ではありません。実際、特にBoxを使い始めたばかりの頃、私もそのように思っていました。Box Platformにおいては、Boxの認証方法に関する多くの質問に対応しています。このブログ記事では、さまざまな選択肢を取り上げてわかりやすく説明します。
認証 — 鍵の多い家
API認証について考えるとき、私は複数の鍵がかかっている家を想像します。各エントリポイントには、ドアの鍵を解除してアクセスを許可するための独自の方法があります。それにもかかわらず、これらの鍵はすべて、共通のデバイス (技術用語ではAPIトークンに相当) によって操作されます。Box Platformの使用も例外ではなく、Boxでは、トークンを取得する4つの方法を提供しています。
- OAuth 2.0
- JSONウェブトークン (略称はJWT)
- クライアント資格情報許可 (略称はCCG)
- App Auth
それぞれの方法を詳しく見ていきましょう。
OAuth 2.0 — 宝箱
お客様が使用する最も一般的な認証方法はOAuth 2.0です。この方法の場合、アプリケーションのユーザーは自分のBoxアカウントを使用してログインする必要があります。つまり、ユーザー自身がBoxを使用していることを認識することになります。私は、一般的にこれをクライアント側認証またはフロントエンド認証と呼んでいます。
お気に入りの宝石が入った宝箱があり、鑑定士にそのいくつかを鑑定してもらいたいと想像してください。しかし、鑑定士には宝箱を丸ごと開ける鍵は渡したくないため、代わりに魔法のバッジを渡します。このバッジを使えば、鑑定士に宝箱を開けさせて、売りたい宝石だけを分析してもらうことができます。鑑定士が宝箱に魔法のバッジをかざすと、そのバッジが本物であり、目的の宝石だけを見るためのものであることが確認されます。また、この魔法のバッジは無期限に機能するわけではありません。鑑定の間だけなど、少しの間しか機能しません。
これはOAuth 2.0とBoxに似ています。あなたが所有しているかアクセス権限を持っているBox内の特定のコンテンツを他のアプリケーションと共有したいと考えている場合、そのコンテンツへのアクセス方法をアプリケーションに提供するには、自分のBoxアカウントにログインします。Boxでは、あなたが本人であり、アプリケーションがアクセスしようとしているコンテンツにアクセスできることが確認されます。Boxは、アプリケーションが想定外の操作 (企業のすべてのユーザーを表示するなど) を行わないようにし、アプリケーションによるアクセスは期限が設定されます。
実例
Boxに保存されているユーザーのファイルにアクセスして、そのファイルをキャンペーンのアセットとして添付するメールマーケティングツール。ユーザーはファイルを個別にアップロードする代わりに、OAuth 2.0ウェブアプリ統合を使用すると、アプリケーションはBox内のユーザーのコンテンツにアクセスできるようになります。
使用に適した状況
- 既存のBoxアカウントを持つユーザーと作業する場合
- ユーザーがBoxを使用していることを認識できるよう、ID管理にBoxを使用する場合
- アプリケーションのサービスアカウント内ではなく、各ユーザーアカウント内にデータを保存する場合
JSONウェブトークン (JWT) — デジタルパスポート
お客様が2番目によく使用する認証方法はJWTです。この方法はアプリケーションのバックグラウンドで行われるため、ユーザーはBoxが使用されていることを認識しません。私は、一般的にこれをサーバー側認証V1と呼んでいます。
海外旅行をすることを想像してみてください。どこに行っても身元を証明するパスポートが必要です。同様に、JSONウェブトークンは、ユーザーのIDに関するクレームを安全に送信することで、API通信のシナリオではデジタルパスポートとして機能します。
Boxでは、JWT認証用のアプリケーションの設定に、BoxのSDKで直接使用できるJSON構成ファイルがあります。この構成ファイルが、前述したパスポートにあたります。
実例
ある大手銀行では、独自のローン申請ポータルを使用して、融資部門を合理化します。顧客は、手続きの一環として、安全な場所に保存する必要のあるさまざまなドキュメントをアップロードします。顧客はBoxアカウントを持っておらず、必要でもありません。代わりにポータルでは、JWT認証を使用するBoxのカスタムアプリケーションを使用します。顧客がポータルでログインを作成すると、コンテンツを保存するためにApp UserがBoxに作成されます。App Userは、Boxのフロントエンドにアクセスできないユーザーです。
使用に適した状況
- Boxアカウントを持たないユーザーと作業する場合
- 独自のIDシステムを使用する場合
- ユーザーにBoxを使用していることを認識させたくない場合
- アプリケーションのサービスアカウント内にデータを保存し、ユーザーのアカウントには保存しない場合
クライアント資格情報許可 (CCG) — VIP用のアクセスバッジ
Boxがリリースした最新の認証方法はCCGです。この方法もアプリケーションのバックグラウンドで行われるため、ユーザーはBoxが使用されていることを認識しません。JWTよりも新しいため、私は、一般的にこれをサーバー側認証V2と呼んでいます。
特別に発行されたバッジにより、承認された参加者だけが入場できる限定イベントへの参加を考えてみましょう。これは、クライアント資格情報許可の仕組みに似ています。これにより、エンドユーザーの操作がなくても、サーバー間通信が可能になります。また、必要なのはBoxのカスタムアプリケーションのクライアントIDとクライアントシークレットのみのため、JWTに必要な「パスポート」よりも使いやすくなっています。
実例
ある分析ソフトウェアでは、レポートを作成する目的で、さまざまなBoxアカウントから使用状況データを取得して分析する必要があります。プラットフォームでは、クライアント資格情報許可を使用して、BoxのカスタムアプリケーションのクライアントIDとシークレットを使用します。このソフトウェアは、BoxのAPIに対してクエリを実行して、ファイル数、ストレージ使用量、コラボレーションアクティビティなどの使用状況データを収集します。収集されたデータを処理して分析し、各Boxアカウントの使用状況レポートとインサイトを生成します。
使用に適した状況
- Boxアカウントを持たないユーザーと作業する場合
- 独自のID管理システムを使用する場合
- ユーザーにBoxを使用していることを認識させたくない場合
- アプリケーションのサービスアカウント内にデータを保存し、ユーザーのアカウントには保存しない場合
アプリトークン認証 — シークレットハンドシェイク
サーバー側のアプリトークン認証は、アプリケーションに、それ自体のアカウントのデータに対する読み取りと書き込みのアクセス権限だけがある認証方法です。これは、Box Viewアプリケーションで使用されます。この認証方法を使用すると、アプリケーションはそのアプリケーションのサービスアカウントとして自動的に認証されるため、ユーザーを承認する必要がありません。
メンバー同士が独自に決められた握手でお互いを仲間と確認する秘密結社の一員であることを想像してみてください。これは、アプリトークンを使用することに似ています。これらのトークンはアプリケーションに固有であり、あらかじめ定義されている権限に基づいてアクセスを許可します。
実例
この方法はBox Viewのユースケースにのみ有効なため、以下に、検討すべき一般的なユースケースを示します。
- 求人アプリケーションで履歴書PDFを変換して表示する
- 学生向けポータルで、ドキュメント、ビデオ、PDFなどの教材を変換して表示する
- メディアルームでHDビデオを変換して表示する
- 現場の営業支援アプリケーションで、ドキュメント、ビデオ、PDF、3Dモデルなどの営業資料を変換して表示する
使用に適した状況
- ユーザーモデルがない環境、またはBoxアカウントを持たないユーザーがいる環境で使用する場合
- 独自のID管理システムを使用する場合
- ユーザーにBoxを使用していることを認識させたくない場合
- アプリケーションのサービスアカウント内にデータを保存し、ユーザーのアカウントには保存しない場合
まとめ
Boxは、アプリケーションの作成時に、OAuth 2.0、JSONウェブトークン (JWT)、クライアント資格情報許可 (CCG)、アプリトークン認証という4種類の認証方法を開発者に提供します。それぞれの方法には、独自のカスタマイズと特定の用途があります。アプリケーションのこの部分の設定は複雑であるため、混乱したり迷ったりしやすくなります。このブログ記事が、認証方法の違いを理解し、現在または将来のアプリケーションをより迅速に作成する際にお役に立てば幸いです。
関連リソース
Node OAuth 2.0のサンプル
Node JWTのサンプル
Box Platformの認証方法に関するこのブログが皆さんのお役に立てば幸いです。質問がある場合は、Developer Forumに英語で投稿してください。