- この記事は、Google Drive™ APIに関する記事を和訳したものです。
- 原文: Authenticate your users
- 元記事のライセンスは CC-BYで、この和訳記事のライセンスは CC-BYです。
- 自己責任でご利用ください。
- 和訳した時期は 2019年6月ころです。
あなたのアプリケーションが Drive APIに送信するすべてのリクエストは、承認トークンを含んでいなければなりません。 さらには、トークンは、あなたのアプリケーションを Googleに識別させます。
承認プロトコルについて
あなたのアプリケーションは、リクエストを承認するために OAuth 2.0を使用しなければなりません。 他の承認プロトコルはサポートされていません。 もしあなたのアプリケーションが Google Sign-Inを使用しているならば、承認の幾つかの側面が処理されます。
OAuth 2.0を用いてリクエストを承認する
Drive APIへのすべてのリクエストは、認証されたユーザによって承認されなければなりません。
承認プロセスの詳細、あるいは OAuth 2.0 のための "flow" は、あなたが書いているアプリケーションの種類に応じて多少変わります。 次の一般的なプロセスは、すべてのアプリケーションタイプに適用されます:
- あなたのアプリケーションを作成するとき、Google API Consoleを使用してそれを登録します。 Googleは、それから、クライアント IDやクライアントシークレットといった、後で必要となる情報を提供します。
- Google API Consoleにて Drive APIをアクティブにします。 (もし APIが API Consoleにリストされていなければ、このステップをスキップします。)
- あなたのアプリケーションがユーザデータへのアクセスを必要とするとき、それは、アクセスの特定のスコープを Googleに尋ねます。
- Googleは、ユーザに同意画面を表示し、彼らに、彼らのデータの幾つかをリクエストするためにあなたのアプリケーションを承認するよう尋ねます。
- もしユーザが承認したならば、Googleは、あなたのアプリケーションに一時的なアクセストークンを与えます。
- あなたのアプリケーションはユーザデータをリクエストし、リクエストにアクセストークンをアタッチします。
- もし Googleが、あなたのリクエストおよびトークンが有効であると判断したならば、それは、リクエストされたデータを返します。
幾つかのフローは、新しいアクセストークンを取得するためにリフレッシュトークンを使用するといった、追加のステップを含みます。 さまざまなアプリケーションのタイプのフローの詳細については、Googleの OAuth 2.0 documentationを参照してください。
Drive APIのための OAuth 2.0スコープ情報は、次のとおりです:
| スコープ | 意味 | 使用方法 |
|---|---|---|
https://www.googleapis.com/auth/drive.appfolder |
アプリケーションデータフォルダへのアクセスを許可します。 | Recommended |
https://www.googleapis.com/auth/drive.file |
アプリによって作成され、あるいは、開かれたファイルへの、ファイルごとのアクセス。 ファイルの承認はユーザごとに付与され、ユーザがアプリを承認解除したときに取り消されます。 | Recommended |
https://www.googleapis.com/auth/drive.install |
ユーザにアプリのインストールを承認させるために使用される特別なスコープ、そして、スコープはリクエストされる必要があります。 | Recommended |
https://www.googleapis.com/auth/drive.apps.readonly |
インストールされたアプリへの読み込み専用のアクセスを許可します。 | Sensitive |
https://www.googleapis.com/auth/drive.metadata |
ファイルのメタデータ(downloadUrlおよび contentHints.thumbnailを除く)への読み込み・書き込みアクセスを許可しますが、ファイルコンテンツを読み込み、ダウンロードし、書き込み、あるいはアップロードするためのアクセスを許可しません。
さらには、アクセスの昇格を防ぐために、フォルダあるいは共有の変更を許可しません。
|
Restricted |
https://www.googleapis.com/auth/drive |
アプリケーションデータフォルダを除く、すべてのユーザのファイルへのアクセスへの完全に許容されたスコープ。 | Restricted |
https://www.googleapis.com/auth/drive.activity |
Drive Activity APIへの読み込み、および書き込みアクセスを許可します。 | Restricted |
https://www.googleapis.com/auth/drive.activity.readonly |
Drive Activity APIへの読み込み専用アクセスを許可します。 | Restricted |
https://www.googleapis.com/auth/drive.readonly |
ファイルのメタデータおよびファイルコンテンツへの読み込み専用のアクセスを許可します。 | Restricted |
https://www.googleapis.com/auth/drive.metadata.readonly |
ファイルのメタデータ(downloadUrlおよび contentHints.thumbnailを除く)への読み込み専用アクセスを許可しますが、ファイルコンテンツを読み込み、ダウンロードするためのアクセスを許可しません。
|
Restricted |
https://www.googleapis.com/auth/drive.scripts |
Apps Scriptファイルへのアクセスを許可します。 | Restricted |
どこで:
-
Recommended - これらのスコープは最小のスコープの承認アクセスを提供し、何らのアプリの検証あるいはセキュリティ評価を必要としません。
-
Sensitive - これらのスコープは Google User Dataへのアクセスを許可し、制限されたスコープの検証プロセスを必要とします。 この要件については、Google API Services: User Data Policyを参照してください。 これらのスコープは、セキュリティ評価を必要としません。
-
Restricted - これらのスコープは Google User Dataへの幅広いアクセスを提供し、あなたが制限されたスコープの検証プロセスを通過させることを必要とします。 詳細については、Google API Services: User Data Policyおよび Additional Requirements for Specific API Scopesを参照してください。 もしあなたのアプリがデータをサーバ上に格納する、あるいは、サーバを介してデータを送信するならば、セキュリティ評価も必要になるかもしれません。
新しいアプリのためにスコープを選択する
あなたのアプリがインストールされるとき、ユーザはアプリによって使用されるスコープを検証するよう求められます。
一般的に、制限されたスコープの使用を検証することを、ユーザが決定する必要がないようにします。
そのため、可能であれば、アプリによって必要とされる特定の機能へのアクセスを狭めるために "recommended" スコープを使用してください。
ほとんどの場合、狭いアクセスを提供することは、https://www.googleapis.com/auth/drive.file ファイルごとのアクセススコープを使用することを意味します。
制限されたスコープの使用が許可されるかもしれないアプリは、2種類のみです:
-
制限されたスコープの使用は、ユーザの Driveファイルのローカル同期あるいは自動的なバックアップを提供する、ネイティブおよびウェブアプリでは許可されるかもしれません。
-
制限されたスコープの使用は、ユーザインターフェイスが Google Driveとのやりとりを伴うかもしれない、生産的の高い、および、教育的なアプリケーションでは許可されるかもしれません。 例えば、もし、あなたのアプリが、ディスカッションにて Drive URLを貼り付けることをユーザに許可するチャットアプリであるならば、制限されたスコープは許可されるかもしれません。 生産性アプリケーションは、タスク管理、メモ書き、ワークグループコミュニケーション、および、教室コラボレーションアプリケーションを含みます。
もし、あなたのアプリが制限されたスコープを必要とすると信じるならば、制限されたスコープの検証およびセキュリティ評価をリクエストするを参照してください。
制限されたスコープの検証およびセキュリティ評価をリクエストする
機密性の高い、あるいは、制限されたスコープを使用するアプリの場合、Google API Servies: User Data Policyおよび Additional Requirements for Specific API Scopesに準拠するために、制限されたスコープの検証が実行されなければなりません。
もしアプリがサーバ上にデータを格納し、あるいは、サーバを介してデータを送信するならば、セキュリティ評価も必要とされます。 あなたのアプリケーションの機密性を保証するために、Googleは、セキュリティ評価を実施するためにサードパーティーのベンダーを使用します。
-
制限されたスコープの検証をリクエストするには、How do I submit for verification?を参照してください。
-
制限されたスコープの検証を合格すると、あなたのセキュリティ評価を実行するために使用することができるサードパーティーのセキュリティ評価者を伴った電子メールが送信されます。
制限されたスコープの検証およびセキュリティ評価についてのよくある質問については、OAuth API Application Verification FAQを参照してください。
既存のアプリを推奨されるスコープにマイグレーションする
もし、あなたのアプリが現在、完全な Driveスコープを使用しており、あなたのアプリのユーザのために承認の範囲を制限したければ、https://www.googleapis.com/auth/drive.file 推奨スコープを使用するようにあなたのアプリをアップデートすることができます。
もし、あなたが制限されたスコープのいずれかを使用する Driveアプリを開発しているならば、私たちは、あなたのアプリが drive.fileスコープを使用するようにマイグレーションすることをお勧めします。
このスコープは、ユーザが Google Driveから、および、Google Pickerを通して、彼らがあなたのアプリにアクセスを許可したい、特定のファイルを選択できるようにします。
drive.fileスコープを使用するアプリは、制限されたスコープの検証およびサードパーティーのセキュリティ評価を通過させる必要はありません。
多くのアプリは、ファイルごとのアクセスを伴って動作し、何らの変更を伴いません。
もし、現在、独自のファイルピッカーを使用しているならば、私たちは、drive.fileスコープを完全にサポートするGoogleファイルピッカーに切り替えることをお勧めします。
他の Google APIにアクセスするためにスコープを追加する
もしあなたのアプリが何らかの他の Google APIへのアクセスを必要とするならば、それらのスコープを追加することもできます。 Google APIのスコープの詳細については、Using OAuth 2.0 to Access Google APIsを参照してください。
OAuth 2.0を使用してアクセスをリクエストするために、あなたのアプリケーションは、スコープ情報、および、あなたがあなたのアプリケーションを登録したときに Googleが提供した情報(クライアント IDやクライアントシークレットといった)を必要とします。
ヒント: Google APIクライアントライブラリは、あなたのために承認プロセスの幾つかを処理することができます。 それらは、さまざまなプログラミング言語で利用可能です; 詳細については、page with libraries and samplesをチェックしてください。
ユーザを認証する
既存のユーザを認証するには、OAuth 2.0および Google's identity APIsを使用します。 それを避けることができるときはいつでも、ユーザに、あなたのアプリケーションのために新しいパスワードを作成させることを要求しないでください。
Create New および Open With イベントのエラーを処理する
すべての Driveアプリは、すべての "Create New" および "Open with" イベントを、潜在的なログインのように扱う必要があります。
幾つかのユーザは、複数のアカウントを持っているかもしれません。
もし stateパラメータ内のユーザ IDが、現在のセッションと一致しないならば、あなたのアプリの現在のセッションを終了し、リクエストされたユーザとしてログインさせる必要があるかもしれません。
拒否されたアクセスリクエストを処理する
ユーザは、あなたのアプリが彼らのファイルにアクセスすることを拒否するために、OAuthダイアログにて No Thanksをクリックすることができます。
もしユーザがアクセスを拒否したならば、クエリパラメータ errorにて access_denied文字列をキャッチし、ユーザフレンドリーなレスポンスを表示してください。
例えば、あなたのプライバシーポリシーへのリンク、および、あなたのアプリが特定の情報を必要とする理由の分かりやすい説明とともに、フレンドリーな別れのメッセージを表示することができます。
OAuthフローへ戻るリンクを提供することもできます。
Perform G Suiteのドメイン全体の権限移譲を実行する
エンタープライズアプリケーションでは、これらの部分を手動での承認なしに、プログラムでユーザデータにアクセスしたいかもしれません。 G Suiteドメインでは、ドメイン管理者は、サードパーティのアプリケーションに、そのユーザのデータへのドメイン全体のアクセスを付与することができます — これは、ドメイン全体の権限移譲と呼ばれます。 この方法で権限を委譲するために、ドメイン管理者は、OAuth 2.0を用いてサービスアカウントを使用することができます。
追加の詳細については、Using OAuth 2.0 for Server to Server Applicationsを参照してください。