- ユーザーがサインインするアプリはユーザーアプリであり、常にOAuth 2.0を使用します。
- 単独で実行されるアプリはサーバーアプリであり、クライアント資格情報許可 (CCG) またはJWTのどちらかを使用します。
認証方法の概要
認証方法は、アプリが正当性を証明する方法と、取得したトークンでアクセスできるコンテンツの範囲によって異なります。
サーバーアプリは、APIを呼び出す前に承認される必要があります。OAuth 2.0アプリは、企業が未公開アプリをデフォルトで非アクティブにしている場合のみ、Boxの管理者または共同管理者が有効化する必要があります。で両方のケースが解説されています。
JWT認証を設定する
Boxのアクセストークンについて確認する
開発者トークンの生成
OAuth 2.0
OAuth 2.0は、ユーザーがアプリケーションに対して、別のアプリケーション内のデータへのアクセスを許可できるようにするオープンスタンダードです。もしGoogleやFacebookでウェブサイトにサインインしたことがあるなら、すでにこの技術を利用しています。Boxも同様のフローを採用しています。アプリがユーザーをBoxに誘導し、ユーザーがログインしてリクエストを承認すると、Boxが承認コードを返し、アプリがそれをアクセストークンと交換します。 トークンはサインインしたユーザーに属するため、アプリはユーザーが所有またはコラボレーションしているコンテンツにのみアクセスでき、作成されるコンテンツはユーザー自身のアカウントに保存されます。 ユーザーがすでにBoxアカウントを所有しており、ユーザー自身でBoxにサインインさせたい場合は、OAuth 2.0を選択します。OAuth 2.0認証について確認する
クライアント資格情報許可
クライアント資格情報許可 (CCG) は、クライアントIDとクライアントシークレットを使用してアプリケーションのIDを検証し、アクセストークンを直接返します。誰もログインしないので、無人で実行するコードに適しています。CCGは、サーバーアプリの作成時に事前選択されています。 各トークンリクエストでは、認証対象となるサブジェクトを指定します。すなわち、アプリケーションのか、アプリの構成上許可されている場合は特定のユーザーです。 エンドユーザーが自分のBoxアカウントを所有していないか、IDシステムを通じてサインインする場合は、バックエンドサービス、自動化、統合にCCGを選択します。これらの場合、各ユーザーは独自のフォルダツリーを備える独立したApp Userを取得できます。クライアント資格情報許可について確認する
JWT
JSONウェブトークン (JWT) を使用したサーバー認証では、アプリはシークレットをそのまま送信するのではなく、秘密キーを使用して有効期間の短いアサーションに署名し、そのアサーションをアクセストークンと交換します。Boxが保持するのは対応する公開キーのみであるため、秘密キーがユーザーのインフラストラクチャ外に出ることはありません。 JWTではCCGと同じサービスアカウントモデルを使用でき、独立したApp Userも使用できます。アサーションがクライアントシークレットを置き換えることはなく、トークンリクエストには引き続きクライアントシークレットが含まれます。このため、JWTでは資格情報を別のものに置き換えるのではなく、交換のプロセスに追加の要素を導入する仕組みとなっています。JWT認証について確認する
CCGとJWTのどちらかの選択
どちらの方法でも、同じサービスアカウント、App User、コンテンツにアクセスするため、選択の判断基準は、アプリがどのように正当性を証明し、資格情報の管理をどこまで独自に行いたいかによります。 セキュリティレビューでキーペアベースの検証が必要な場合、または秘密キーを自社のインフラストラクチャ内に保持したい場合は、JWTを選択してください。Boxは公開キーのみを保存するため、クライアントシークレットが漏えいしても、それだけではトークンを取得することはできません。その際のコストは、キーペアの生成、秘密キーとそのパスフレーズの保護、ローテーション時の新しい公開キーのアップロードなど、キー管理に関連するものです。 それ以外の場合はCCGを選択してください。CCGはキーやアサーション署名が不要なため、よりシンプルな選択肢となっており、Boxがほとんどのサーバーアプリで推奨している方法です。 すでにアプリが存在する場合に方法を変更できるかどうかは、Enterprise設定によって異なります。方法を変更すると、以前の方法に関連付けられていた資格情報は取り消されます。既存アプリのCCGとJWTの切り替え
方法ごとの資格情報
方法ごとに異なる値のセットが必要であり、それらはすべてのアプリの [構成] タブから取得できます。クライアントシークレットの表示やキーペアの生成に際しては、Boxアカウントで多要素認証 (MFA) を有効にしておく必要があります。
資格情報ファイルがある場所
認証方法としてJWTを選択した場合のみ、Boxからユーザーにファイルを渡す処理が発生します。開発者コンソールで [公開/秘密キーペアを生成] を選択すると、キーペアと認証に必要なアプリケーションの詳細が記載されたconfig.jsonがダウンロードされます。そのファイルをソースコントロールの外部の安全な場所に保管しておき、実行時に読み込んでください。あるいは、同じ値を環境変数やシークレットマネージャから読み込むという方法もあります。ファイルの内容とその読み込み方法の詳細については、ガイドを参照してください。
独自のキーペアを生成し、公開キーのみをアップロードした場合には、config.jsonのダウンロードは発生しません。秘密キーはアプリケーションが起動時に読み取ることができる場所、パスフレーズはキーとは別の場所に、それぞれ保管しておいてください。残りの値は、[構成] タブで確認のうえ読み込ませます。OAuth 2.0とCCGを使用するアプリではファイルが存在しないため、クライアントIDとクライアントシークレットは環境変数やシークレットマネージャに保存してください。
認証のベストプラクティスを確認する
アクセストークン
どの方法でも、最終的な流れは同じです。Boxからアクセストークンが返されると、アプリがそのトークンを各APIコールのAuthorizationヘッダーに追加して送信します。トークンの有効期間は60分間ですが、正確な有効期間はレスポンスのexpires_inという項目に秒単位で記載されています。
各方法のトークンのリクエスト方法
どの方法でも、トークンのリクエスト元エンドポイントがhttps://api.box.com/oauth2/tokenであるという点は共通していますが、送信するgrant_typeとそれに付随するパラメータは異なります。OAuth 2.0の場合、このリクエストは最後に送られます。具体的には、ユーザーがBoxへのサインインと同意を終えた後にリクエストが送信されます。
codeが必要になります。これに対してJWTでは、秘密キーを使って署名したアサーションが必要です。ガイドでは、このアサーションの構築方法を解説しています。なお、を使えば、どちらの手順も自動化が可能です。
返されるもの
トークンと一緒に送られてくるものは方法に応じて異なり、それによってトークンの有効期限が切れた後のアプリの動作が変わります。
更新トークンの有効期間は60日間で、使用できるのは1回のみです。そのため、OAuth 2.0アプリではユーザーごとに最新の更新トークンを保存し、更新がないまま60日が経過したユーザーに対しては承認を再送します。CCGアプリとJWTアプリの場合には、新しいトークンが必要になった時点でリクエストするので、このような処理は発生しません。
トークンが表すユーザー
アクセストークンはいずれも1名のBoxユーザーにマッピングされており、アプリがアクセスできる範囲と新しいコンテンツの保存先は、そのユーザーによって決まります。もっとも、トークンがコンテンツに対して何ができるかは、ユーザーに与えられている権限よりもさらに狭く、ユーザーのアクセス権限と、ユーザーがアプリケーションに許可したが重なり合う範囲のみに限定されます。そのため、ユーザーがファイルを閲覧できる場合でも、呼び出しに失敗することがあります。
Boxアカウントにはそれぞれに独自のフォルダツリーが用意されており、そのツリーのルートはいずれもフォルダID
0となっています。そのため、同じアップロード呼び出しであっても、一緒に送信するトークンに応じてアップロード先が変わることがあります。OAuth 2.0トークンの場合には、サインイン済みのユーザーのアカウントにファイルがアップロードされます。これに対して、サービスアカウントトークンの場合には、(他のユーザーに共有するまでは) そのアプリケーション以外はアクセスできない場所にファイルがアップロードされます。ツリーの垣根を越えてファイルが移動することはないため、アプリが既存のコンテンツを操作する必要がある場合には、あらかじめアカウントにアクセス権限を付与しておく必要があります。
サービスアカウント
サービスアカウントは、プログラムによる仮想的なユーザーで、Box Enterprise内のアプリケーションを表すものです。サービスアカウントは、JWTアプリやCCGアプリがされた時点で自動的に生成されるため、ユーザーが自ら作成することはありません。ログイン資格情報はなく、さまざまな操作をAPI経由で行うことから、バックエンド統合に適しています。サービスアカウントのメールアドレス@boxdevedition.comは、アプリの [アプリの詳細] タブで確認できます。隣には、コンテンツマネージャでそのアカウントを開くためのリンクも用意されています。
サービスアカウントは、最初はフォルダツリーが空になっており、ユーザーがアクセス権限を与えるまでは、既存のファイルにアクセスできません。サービスアカウントのメールアドレスを使ってコラボレータとして招待するか、ユーザーIDを指定してを呼び出します。ストレージ容量、スコープ、管理者がコンテンツを閲覧できる方法は、によって決まります。
サーバーアプリで扱えるのは、サービスアカウントだけではありません。CCGアプリは、をリクエストできます。JWTアプリは、ヘッダーを送信したり、をリクエストしたりできます。いずれの場合でも、管理対象ユーザーとApp Userはそれぞれ独自のフォルダツリーを保持します。