OneDrive の認証とサインイン
Microsoft Graph の使用
このトピックでは、OneDrive 個人用の Microsoft アカウントを使用してアプリケーションを認証する方法について説明します。 ただし、この方法は非推奨になっています。 新しいアプリケーションは、Microsoft Graph を使用して開発して、「Microsoft Graph での OneDrive の認証とサインイン」の認証プロセスに従うようにする必要があります。
はじめに
OneDrive API を使用するには、ユーザーの代わりに特定のアクセス許可のセットでアプリを認証するアクセス トークンが必要になります。 このセクションでは、次に示す操作の方法について説明します。
- アプリケーションを登録して、クライアント ID およびシークレットを取得する。
- トークン フローまたはコード フローを使用して、指定したスコープで OneDrive にユーザーをサインインする。
- ユーザーをサインアウトする (オプション)。
OneDrive API は、標準の OAuth 2.0 認証方式を使用してユーザーを認証し、アクセス トークンを生成します。 アクセス トークンは、次に示す方法で API 呼び出しごとに提示します。
- HTTP ヘッダー:
Authorization: bearer {token}
アプリを登録する
アプリを認証するには、アプリを Microsoft に登録して、いくつかのアプリ関する詳細を提出する必要があります。
アプリを登録するには:
アプリの登録方法の詳細については、OneDrive API のアプリ登録に関するトピックを参照してください。
ユーザーをサインインする
アプリでは、特定のスコープを指定して、Microsoft アカウント認証 Web サービスに接続することでサインイン プロセスを開始し、アクセス トークンを受け取る必要があります。 このフローは、標準の OAuth 2.0 認証フローに従い、Web ブラウザーまたは Web ブラウザー コントロールからの呼び出しが必要です。
認証のスコープ
スコープにより、ユーザーのサインイン時にアプリに付与されるアクセスのタイプが決定されます。 すべてのスコープが Web でのシングル サインオンをサポートしています。つまり、ユーザーが既に OneDrive にサインインしている場合、そのユーザーは認証フローを省略して承認フローに直行できるということです。
| スコープ名 | 説明 | 必須 |
|---|---|---|
| offline_access | ユーザーがアクティブでない場合でも、アプリがオフラインで動作できるようにします。 アプリは refresh_token を取得します。これは、追加のアクセス トークンの生成が必要になったときに使用できます。 このスコープは、トークン フローでは使用できません。 | いいえ |
| onedrive.readonly | ユーザーのすべての OneDrive ファイル (そのユーザーに共有されているファイルを含む) への読み取り専用アクセス許可を付与します。 | はい |
| onedrive.readwrite | ユーザーのすべての OneDrive ファイル (そのユーザーに共有されているファイルを含む) への読み取りおよび書き込みアクセス許可を付与します。 共有リンクを作成する場合は、このスコープが必要になります。 | はい |
| onedrive.appfolder | アプリケーションに、特定のフォルダーへの読み取りおよび書き込みアクセス許可を付与します。 | はい |
その一例として、一般的なプリケーションでは次に示すようなスコープを要求します。
onedrive.readwrite offline_access
サポートされている認証フロー
次に示す、2 つのサポートされている認証フローから選択します。
トークン フロー
トークン フローは、最も簡単な認証フローです。 このフローは、OneDrive API を使用するためのアクセス トークンを対話方式ですばやく取得する場合に便利です。 このフローでは、更新トークンが提供されないため、OneDrive API への長期間アクセスには使用できません。
トークン プロセスでサインイン プロセスを開始するには、Web ブラウザーまたは Web ブラウザー コントロールを使用して URL 要求を読み込みます。
GET https://login.live.com/oauth20_authorize.srf?client_id={client_id}&scope={scope}
&response_type=token&redirect_uri={redirect_uri}
必須のクエリ文字列パラメーター
| パラメーター名 | 値 | 説明 |
|---|---|---|
| client_id | string | アプリケーション用に作成されたクライアント ID 値。 |
| redirect_uri | string | 認証完了時のブラウザーの送信先になるリダイレクト URL。 |
| response_type | string | 認証フローから予測されるリソースのタイプ。 このフローの場合、この値は必ず token になります。 |
| scope | string | アプリケーションが必要とするスコープのスペース区切りのリスト。 |
このリダイレクト URL は、モバイルおよびデスクトップ アプリケーションの場合は https://login.live.com/oauth20_desktop.srf を使用します。
応答
アプリケーションの認証と承認の成功時に、Web ブラウザーはリダイレクト URL にリダイレクトされます。この URL には追加のパラメーターが付加されています。
https://login.live.com/oauth20_authorize.srf#access_token=EwC...EB
&authentication_token=eyJ...3EM&token_type=bearer&expires_in=3600
&scope=onedrive.readwrite&user_id=3626...1d
上記の例では、access_token、authentication_token、および user_id の値が切り詰められています。 access_token と authentication_token の値は、非常に長いものです。
access_token の値は、OneDrive API への要求に使用できます。
コード フロー
認証のコード フローは 3 段階のプロセスであり、アプリケーションの認証および承認のための呼び出しと、OneDrive API を使用するためのアクセス トークン生成の呼び出しにわかれています。 これにより、アプリケーションは更新トークンも受け取れるようになります。更新トークンは、一部のシナリオで API の長期間の使用を可能にするもので、ユーザーがアクティブにアプリケーションを使用しない場合のアクセスが可能になります。
手順 1. 認証コードを取得する
コード フローでサインイン プロセスを開始するには、Web ブラウザーまたは Web ブラウザー コントロールを使用して、この URL 要求を読み込みます。
GET https://login.live.com/oauth20_authorize.srf?client_id={client_id}&scope={scope}
&response_type=code&redirect_uri={redirect_uri}
必須のクエリ文字列パラメーター
| パラメーター名 | 値 | 説明 |
|---|---|---|
| client_id | string | アプリ用に作成されたクライアント ID。 |
| scope | string | アプリが必要とするスコープのスペース区切りのリスト。 |
| redirect_uri | string | 認証完了時のブラウザーの送信先になるリダイレクト URL。 |
| response_type | string | 認証フローから予測されるリソースのタイプ。 このフローの場合、この値は必ず code になります。 |
応答
アプリケーションの認証と承認の成功時に、Web ブラウザーはリダイレクト URL にリダイレクトされます。この URL には追加のパラメーターが付加されています。
https://login.live.com/oauth20_authorize.srf?code=df6aa589-1080-b241-b410-c4dff65dbf7c
手順 2. コードをアクセス トークンと交換する
code の値を受け取ったら、このコードをトークンのセットに交換できます。このセットにより、OneDrive API での認証が可能になります。 コードを交換するには、次に示す要求を送信します。
POST https://login.live.com/oauth20_token.srf
Content-Type: application/x-www-form-urlencoded
client_id={client_id}&redirect_uri={redirect_uri}&client_secret={client_secret}
&code={code}&grant_type=authorization_code
要求本文の必須パラメーター
要求本文は、適切にエンコードされた URL 文字列であり、いくつかの必須パラメーターが含まれています。
| パラメーター名 | 値 | 説明 |
|---|---|---|
| client_id | string | アプリケーション用に作成されたクライアント ID 値。 |
| redirect_uri | string | 認証完了時のブラウザーの送信先になるリダイレクト URL。 これは、最初の要求に含まれる redirect_uri と一致している必要があります。 |
| client_secret | string | アプリケーション用に作成されたクライアント シークレット。 |
| code | string | 最初の認証要求で受け取った認証コード。 |
メモ Web アプリの場合、リダイレクト URI のドメイン部分は、 Microsoft アカウントデベロッパー センターで指定したリダイレクト URI のドメイン部分と一致する必要があります。
応答
呼び出しに成功すると、POST 要求の応答内の JSON 文字列には複数のプロパティが含まれます。このプロパティには、access_token、token_type、および refresh_token (wl.offline_access スコープを要求した場合) が含まれます。
{
"token_type":"bearer",
"expires_in": 3600,
"scope":"wl.basic onedrive.readwrite",
"access_token":"EwCo...AA==",
"refresh_token":"eyJh...9323"
}
この時点で、認証済みの要求を OneDrive API に送信するために提示する access_token を保存して使用できます。
重要: この応答に含まれる access_token と refresh_token の値は、ユーザーのパスワードと同じように安全に取り扱ってください。
アクセス トークンは、expires_in プロパティで指定された秒数だけ有効です。 新しいアクセス トークンは、更新トークンを使用して要求します (使用可能な場合)。それ以外の場合は、認証要求を最初から繰り返します。
手順 3. 新しいアクセス トークンまたは更新トークンを取得する
アプリで wl.offline_access へのアクセスを要求していた場合は、この手順によって refresh_token が返されます。これは、最初のトークンの失効後に、追加のアクセス トークンを生成するために使用できます。
更新トークンを新しいアクセス トークンに交換するには、次に示す要求を送信します。
POST https://login.live.com/oauth20_token.srf
Content-Type: application/x-www-form-urlencoded
client_id={client_id}&redirect_uri={redirect_uri}&client_secret={client_secret}
&refresh_token={refresh_token}&grant_type=refresh_token
要求本文の必須パラメーター
要求本文は、適切にエンコードされた URL 文字列であり、いくつかの必須パラメーターが含まれています。
| パラメーター名 | 値 | 説明 |
|---|---|---|
| client_id | string | アプリケーション用に作成されたクライアント ID。 |
| redirect_uri | string | 認証完了時にブラウザーの送信先となるリダイレクト URL。 これは、最初の要求で使用される redirect_uri 値と一致する必要があります。 |
| client_secret | string | アプリケーション用に作成されたクライアント シークレット。 |
| refresh_token | string | 以前に受信した更新トークン。 |
メモWeb アプリの場合、リダイレクト URI のドメイン部分は、Live SDK アプリ管理サイトで指定したリダイレクト URI のドメイン部分と一致する必要があります。
応答
呼び出しに成功すると、POST 要求の応答内の JSON 文字列には複数のプロパティが含まれます。このプロパティには、access_token および authentication_token が含まれ、wl.offline_access スコープを要求した場合は refresh_token も含まれます。
{
"token_type":"bearer",
"expires_in": 3600,
"scope": "wl.basic onedrive.readwrite wl.offline_access",
"access_token":"EwCo...AA==",
"refresh_token":"eyJh...9323"
}
この時点で、OneDrive API に認証済みの要求を送信するための access_token を保存して使用できます。
重要: この応答に含まれる access_token と refresh_token の値は、ユーザーのパスワードと同じように安全に取り扱ってください。
アクセス トークンは、expires_in プロパティで指定された秒数だけ有効です。 新しいアクセス トークンは、更新トークンを使用して要求します (使用可能な場合)。または、認証要求を最初から繰り返します。
ユーザーをサインアウトする
ユーザーをサインアウトするには、次の手順を実行します:
- 前の手順で OAuth フローから受け取った、キャッシュ済みの
access_tokenとrefresh_tokenの値を削除します。 - アプリケーションで、すべてのサインアウト操作を実施します (たとえば、ローカルの状態のクリーンアップ、すべてのキャッシュ アイテムの削除など)。
- この URL を使用して認証 Web サービスを呼び出します。
GET https://login.live.com/oauth20_logout.srf?client_id={client_id}&redirect_uri={redirect_uri}
この呼び出しにより、シングル サインオンの実行を可能にする Cookie を削除して、次回アプリがサインイン エクスペリエンスを開始したときには、ユーザー名とパスワードを再度入力して続行するようにユーザーに要求します。
必須のクエリ文字列パラメーター
| パラメーター名 | 値 | 説明 |
|---|---|---|
| client_id | string | アプリケーション用に作成されたクライアント ID 値。 |
| redirect_uri | string | 認証完了時のブラウザーの送信先になるリダイレクト URL。 これは、トークンの取得要求に使用した redirect_uri 値と正確に一致している必要があります。 |
Cookie の削除後、ブラウザーは指定のリダイレクト URL にリダイレクトされます。 ブラウザーがリダイレクト ページを読み込むときには、認証クエリ文字列パラメーターは設定されなくなり、ユーザーがログアウトされていることがわかります。
アクセス権の取り消し
ユーザーは、Microsoft アカウント管理の同意ページにアクセスすることで、自分のアカウントに対するアプリのアクセス権を取り消しできます。
アプリに関する同意が取り消された場合、以前にアプリに対して提供されたすべての更新トークンは無効となります。 新しいアクセス トークンと更新トークンを要求するための認証フローを最初から繰り返す必要があります。
エラー
認証でエラーが発生すると場合、Web ブラウザーはエラー ページにリダイレクトされます。 エラー ページには、ユーザーにとってわかりやすいメッセージが常に表示されますが、エラー ページの URL には発生した問題の解決に役立つ可能性がある追加情報が含まれています。 この情報は、ブラウザーに表示されるエラー ページの内容では示されないことがあります。
https://login.live.com/err.srf?lc=1033#error={error_code}&error_description={message}
この URL には、それぞれエラーと応答の解析に使用できるクエリ パラメーターが含まれています。 これらのパラメーターは、常にブックマークとして (# 文字の後に) 含まれます。 ページのコンテンツでは、常にユーザーに向けた一般的なエラー メッセージを表示します。
ユーザーがアプリケーションに同意を与えない場合、フローは redirect_uri にリダイレクトして、同じエラー パラメーターを含めます。
エラー パラメーター
| パラメーター名 | 値 | 説明 |
|---|---|---|
| error | string | 発生したエラーを識別するエラー コード。 |
| error_description | string | エラーの説明。 |
関連項目
次に示すトピックでは、その他の OneDrive API に該当する大まかな概要について説明しています。