目次
1. スコープ指定アプリの導入
Dropbox では、最近、複数の権限の拡張に着手しました。その内容については、OAuth ガイドまたはブログ投稿「Dropbox API：スコープ指定アプリと強化された認可フロー」でご紹介しています。ここでの大きな変更点は、短期アクセス トークン、スコープ、PKCE、そして更新トークンの導入です。今のところ、アプリ コンソールでは、レガシー アプリとスコープ指定アプリの両方を作成できます。ただし Dropbox では、2021 年 9 月 30 日に長期アクセス トークンを廃止する準備を進めており、その後まもなく、長期アクセス トークンを使用するアプリは作成できなくなる可能性があります。つまり、以下のことが必要となります。
- スコープに移行するために、アプリの［Permission（権限）］タブを確認する（コードの変更は必要ありません）。
- 短期アクセス トークンでアプリが動作することを確認する（コードの変更が必要になる可能性があります）。
2. 権限の更新
アプリの設定で［Permissions（権限）］タブに移動すると、アプリのレガシー アクセス タイプに基づいてスコープが事前に選択されます。たとえば、Business API を使用し、Team auditing（チーム監査）を指定しているアプリには、team_info.read、members.read、groups.read、events.read があらかじめ選択されます。User API を使用しているアプリには、すべてのユーザー スコープが事前に選択されます。
設定を変更しなくても、最後までクリックして進めていけば、アプリは引き続き動作します。ただし、アプリに不要なスコープは選択を解除することを強くお勧めします。このようにしておくと、全体的なセキュリティが強化され、ユーザーにリクエストする権限も少なくなります。
2-1. 必須スコープの特定
アプリが使用するエンドポイントのリストを作成します。HTTP リファレンス資料で各エンドポイントを確認し、「必須スコープ」を記録します。
Dropbox API ドキュメントに掲載されている、エンドポイントの「Required Scope（必須スコープ）」フィールドのスクリーンショット
たとえば、オンライン フォト編集ツールのアプリを移行するとします。アプリが使用する各エンドポイントについて、対応するスコープを記録していきます。
| エンドポイント | 必須スコープ |
|---|---|
| /users/get_current_account | account_info.read |
| /files/list_folder（および /continue） | files.metadata.read |
| /files/get_thumbnail | files.content.read |
| /files/download | files.content.read |
| /files/upload | files.content.write |
作成したリストどおりにアプリのスコープを設定すると、アプリにはこれらのエンドポイントへのアクセスに必要な権限が設定されます。適切なスコープを指定せずに、エンドポイントへの API コールを行うと、エラーがスローされます。
2-2. プログラムによるスコープの設定
移行後、特定のスコープのグループを使用してアプリをテストするには、承認 URL でそのスコープを渡します。この方法は、不要なスコープの選択を解除する前に、スコープのグループをテストするために実施できます。
https://www.dropbox.com/oauth2/authorize? client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&scope=files.content.read&account_info.read
2-3. スコープへの権限の移行
アプリ コンソール内で、レガシーの権限モデルを使用しているアプリの［Settings（設定）］ページに移動して、［Permissions（権限）］タブをクリックします。移行プロセスの詳細を示す、背景が水色のメッセージに注意してください。アプリで使用していないスコープの選択を解除します。アプリが依存している機能が動作しなくなる可能性があるため、スコープの選択を解除するときは注意してください。不要なスコープの選択を解除する前に、アプリを監査し、必須スコープを特定しておくことをお勧めします。 その他のスコープは必要に応じて後で追加または削除できます。
Dropbox アプリのアプリ設定に表示される［Permissions（権限）］タブのスクリーンショット
［Migrate（移行）］、［Confirm（確認）］の順にクリックします。この変更は、既存のトークンに影響しません。承認フローを実行して、スコープをテストします。これで、アプリを移行してスコープを使用できるようになりました。次に、長期アクセス トークンは今後廃止される予定であるため、短期アクセス トークンに移行することをお勧めします。
3. アクセス トークン タイプの更新
ユーザーが Dropbox API とやり取りするときにアプリが 401 ステータスのエラーを正しく処理し、Dropbox API を呼び出すだけであれば、コードの変更は必要ありません。アプリが 401 エラーを正しく処理しない、またはユーザーの入力なしで Dropbox API とやり取りする必要がある場合（「オフライン」アクセス）は、コードの変更が必要になる可能性があります。
3-1. token_access_type を使用した短期アクセス トークンのテスト
短期アクセス トークンにアプリを移行する前に、アプリでこれらのトークンをテストすることをお勧めします。コードを少し調整するだけで、プログラムによって短期アクセス トークンを発行できます。調整は、承認 URL で token_access_type=online と指定するだけです。
https://www.dropbox.com/oauth2/authorize? client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&token_access_type=online
移行中にこの方法に着手することをお勧めします。アプリの動作に確信が持てるようになったら、アプリ コンソールでデフォルトのアクセス トークン タイプを「短期」に更新します。アプリに対して適切な承認フローを設定する方法の詳細については、OAuth ガイドを参照してください。
3-2. 承認エラーの処理
ユーザーが、無効なトークンを使用してアプリにアクセスしようとした場合は、OAuth フローで使用する承認 URL にユーザーをリダイレクトします。ユーザーがすでにアプリを承認している（かつ Dropbox にログインしている）場合、新しい短期アクセス トークンが発行され、ユーザーは、入力しなくてもアプリにリダイレクトされます。このプロセスによって、以前より再認証のフローが多くなりますが、エンド ユーザーのエクスペリエンスに対する影響は最小限で済みます。
ユーザーがアクティブにアプリとやり取りしていて（オンライン アクセス）、401 エラー時に再認証を求める処理について OAuth のベスト プラクティスに従っている場合に、アプリが Dropbox API を呼び出すだけであれば、アプリで短期アクセス トークンを使用するためにコードを変更する必要はありません。
3-3. 更新トークンの実装
以下のアプリが対象です。
- ユーザーが使用中かどうかに関係なく、長期間のアクセスが必要になるアプリ（ログイン状態を維持するモバイル アプリ）
- ユーザーがアクティブにアプリとやり取りしないときに、Dropbox API とやり取りする必要があるアプリ（「オフライン」アクセス）
Dropbox では、新しい短期アクセス トークンをリクエストする場合に使用できる長期の refresh_token を提供しています。
承認 URL のパラメータとして、オフラインのトークン アクセス タイプ（ token_access_type=offline ）を宣言することで、アクセス トークンのペイロードの一部として refresh_token をリクエストします。
https://www.dropbox.com/oauth2/authorize? client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&token_access_type=offline
次に、/oauth2/token へのリクエストを実施します。
curl https://api.dropbox.com/oauth2/token \
-d code=<AUTHORIZATION_CODE> \
-d grant_type=authorization_code \
-d redirect_uri=<REDIRECT_URI> \
-u <APP_KEY>:<APP_SECRET>
結果のペイロードには refresh_token が含まれます。
{
uid": "267161268",
"access_token": "Your_Access_token",
"expires_in": 14399,
"token_type": "bearer",
"scope": "files.content.read files.metadata.read sharing.read sharing.write",
"refresh_token": "LwlUmqpmGqgAAAAAAAAEYgRoVJoei4u9cC7cDHFBAp0Kkp2JNciPxQpNWGY",
"account_id": "dbid:AABuTtSGJM0ME3t4m85i1o3XqnmXvwH5I-A"
}
ここで、/oauth2/token エンドポイントから新しいトークンをリクエストするときに、 grant_type を refresh_token に設定し、パラメータとして refresh_token を指定します。
curl https://api.dropbox.com/oauth2/token \
-d grant_type=refresh_token \
-d refresh_token=<YOUR_REFRESH_TOKEN> \
-u <YOUR_APP_KEY>:<YOUR_APP_SECRET>
3-4. デフォルトのトークン タイプの更新
レガシー アプリの「Settings（設定）」ページ（アプリ コンソールからアクセス）で、OAuth 2 設定のセクションに移動します。新しく作成した、スコープ指定アプリのデフォルトは、短期アクセス トークンになります。
Dropbox アプリの設定ページの［OAuth 2］フィールドに表示されるアクセス トークンの有効期限の設定
アクセス トークンの有効期限の設定
［Access token expiration（アクセス トークンの有効期限）］プルダウンをクリックし、［Short-lived（短期）］を選択します。これで、アプリはデフォルトで短期アクセス トークンを使用します。短期アクセス トークンは、「短い」期間で期限切れになりますが、通常、その期間は、妥当なウェブ セッションであれば十分な長さです。アクセス トークンが有効な期間は、アクセス トークン ペイロードの expires_in パラメータで返されます。アプリに「オフライン」アクセスが必要な場合は、上記の更新トークンの実装セクションを参照してください。
4. レガシー トークンの廃止
2021 年 9 月 30 日をもって、Dropbox は、長期アクセス トークンの作成機能を廃止する予定です。その後、新しいトークンは、すべて短期アクセス トークンとなります。すでに再認証を処理しているオンラインのみのアプリの場合は、ユーザーが再認証を求められる回数が増える可能性があります。バックグラウンド（「オフライン」）アクセスが必要なアプリは、まだ更新トークンを実装していない場合に影響を受けます。
5. サポートのお問い合わせ先
Dropbox では、この変更についてサポート体制を整えています。移行プロセスについてご不明な点がある場合、役に立つ具体的なリソースや例をご希望の場合は、デベロッパー フォーラムのスコープに関するディスカッションのスレッドに投稿してお知らせください。また、個別に直接のサポートをご希望の場合は、サポート リクエスト フォームでご連絡ください。
Dropbox を使用した開発についての詳細は、www.dropbox.com/developers をご覧ください。
