Microsoft Graph での OneDrive の認証とサインイン
Microsoft Graph から OneDrive API を使用する場合は、ユーザーの代わりに特定のアクセス許可のセットでアプリを承認するアクセス トークンを取得する必要があります。 このセクションでは、次に示す操作の方法について説明します。
- アプリケーションを登録して、アプリケーション ID を取得する。
- トークン フローまたはコード フローを使用して、指定したスコープでユーザーをサインインする。
- ユーザーをサインアウトする (オプション)。
OneDrive API は、標準の OAuth 2.0 認証フレームワークを使用して、アプリの承認とアクセス トークンの生成を実施します。 アクセス トークンは、次に示すように、認証された API 呼び出しごとに HTTP ヘッダーを使用して提示する必要があります。
Authorization: bearer {token}
注: Azure AD v2.0 エンドポイントを使用する認証フレームワークが推奨されています。 ただし、一部のエンタープライズ シナリオでは、オリジナルの Azure AD エンドポイントの使用が必要になることがあります。 詳細については、「Microsoft Graph でのアプリ認証」を参照してください。
アプリを登録する
最初の手順では、アプリを Microsoft に登録して、アプリに関するいくつかの詳細を提出します。 アプリケーションを登録し、Azure アプリ登録ページから新しいアプリ ID を受け取ることができます。
アプリケーションの登録方法の詳細な手順は、「OneDrive API のアプリを登録する」を参照してください。
ユーザーをサインインする
アプリのサインインプロセスは、特定のスコープで Azure Active Directory 認証エンドポイントと通信することで開始する必要があります。 このフローは、標準の OAuth 2.0 承認フローに従い、Web ブラウザーまたは Web ブラウザー コントロールからの呼び出しが必要になります。 認証フローの結果として、アクセス トークンが返されます。また、オプションで、アプリが API へのアクセスに使用する別のトークンも返されます。
認証のスコープ
スコープにより、ユーザーのサインイン時にアプリに付与されるアクセスのタイプが決定されます。 すべてのスコープが Web でのシングル サインオンをサポートしています。つまり、ユーザーが既に OneDrive にサインインしている場合、そのユーザーは認証フローを省略して承認フローに直行できるということです。
| スコープ名 | 説明 |
|---|---|
| offline_access | ユーザーがアクティブでない場合でも、アプリがオフラインで動作できるようにします。 コード フローを使用する必要があります。 |
| files.read | ユーザーのすべての OneDrive ファイルへの読み取り専用アクセス許可を付与します。 |
| files.read.all | ユーザーのすべての OneDrive ファイル (そのユーザーに共有されているファイルを含む) への読み取り専用アクセス許可を付与します。 |
| files.readwrite | ユーザーのすべての OneDrive ファイルへの読み取りおよび書き込みアクセス許可を付与します。 |
| files.readwrite.all | ユーザーのすべての OneDrive ファイル (そのユーザーに共有されているファイルを含む) への読み取りおよび書き込みアクセス許可を付与します。 |
その一例として、一般的なプリケーションでは次に示すようなスコープを要求します。
files.readwrite offline_access
サポートされている認証フロー
Azure Active Directory は複数の認証フローをサポートしていますが、ここでは、次に示す最も一般的な 2 つのフローの概要を示します。
トークン フロー
トークン フローは、最も簡単な認証フローです。 このフローは、OneDrive API を使用するためのアクセス トークンを対話方式ですばやく取得する場合に便利です。 このフローでは更新トークンが提供されないため、リソースへの長時間にわたるアクセスには適していません。
トークン プロセスでサインイン プロセスを開始するには、Web ブラウザーまたは Web ブラウザー コントロールを使用して URL 要求を読み込みます。
GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?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 | アプリケーションが必要とするスコープのスペース区切りのリスト。 |
応答
アプリケーションの認証と承認の成功時に、Web ブラウザーは指定のリダイレクト URL にリダイレクトされます。この URL には追加のパラメーターが付加されています。
https://myapp.com/auth-redirect#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 の値は、Microsoft Graph への要求に使用できます。
コード フロー
認証のコード フローは 3 段階のプロセスであり、アプリケーションの認証および承認のための呼び出しと、OneDrive API を使用するためのアクセス トークン生成の呼び出しにわかれています。 これにより、アプリケーションは更新トークンも受け取れるようになります。更新トークンは、一部のシナリオで API の長期間の使用を可能にするもので、ユーザーがアクティブにアプリケーションを使用しない場合のアクセスが可能になります。
手順 1. 認証コードを取得する
コード フローでサインイン プロセスを開始するには、Web ブラウザーまたは Web ブラウザー コントロールを使用して、この URL 要求を読み込みます。
GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?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://myapp.com/auth-redirect?code=df6aa589-1080-b241-b410-c4dff65dbf7c
手順 2. コードをアクセス トークンと交換する
code の値を受け取ったら、このコードをトークンのセットに交換できます。このセットにより、OneDrive API での認証が可能になります。
コードを交換するには、次に示す要求を送信します。
POST https://login.microsoftonline.com/common/oauth2/v2.0/token
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"
}
この時点で、認証済みの要求を Microsoft Graph に送信するために提示する access_token を保存して使用できます。
重要: この応答に含まれる access_token と refresh_token の値は、ユーザーのパスワードと同じように安全に取り扱ってください。
アクセス トークンは、expires_in プロパティで指定された秒数だけ有効です。 新しいアクセス トークンは、更新トークンを使用して要求します (使用可能な場合)。それ以外の場合は、認証要求を最初から繰り返します。
手順 3. 新しいアクセス トークンまたは更新トークンを取得する
アプリで offline_access スコープを要求していた場合は、この手順によって refresh_token が返されます。これは、最初のトークンの失効後に、追加のアクセス トークンを生成するために使用できます。
更新トークンを新しいアクセス トークンに交換するには、次に示す要求を送信します。
POST https://login.microsoftonline.com/common/oauth2/v2.0/token
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 のドメイン部分は、 Microsoft デベロッパー センターで指定したリダイレクト URI のドメイン部分と一致する必要があります。
応答
呼び出しに成功すると、POST 要求の応答内の JSON 文字列には、いくつかのプロパティが含まれます。このプロパティには、access_token と authentication_token が含まれています。また、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"
}
この時点で、Microsoft Graph に認証済みの要求を送信するための access_token を保存して使用できます。
重要: この応答に含まれる access_token と refresh_token の値は、ユーザーのパスワードと同じように安全に取り扱ってください。
アクセス トークンは、expires_in プロパティで指定された秒数だけ有効です。 新しいアクセス トークンは、更新トークンを使用して要求します (使用可能な場合)。または、認証要求を最初から繰り返します。
ユーザーをサインアウトする
ユーザーをサインアウトするには、次の手順を実行します:
- 前の手順で OAuth フローから受け取った、キャッシュ済みの
access_tokenとrefresh_tokenの値を削除します。 - アプリケーションで、すべてのサインアウト操作を実施します (たとえば、ローカルの状態のクリーンアップ、すべてのキャッシュ アイテムの削除など)。
- この URL を使用して認証 Web サービスを呼び出します。
GET https://login.microsoftonline.com/common/oauth2/v2.0/logout?post_logout_redirect_uri={redirect-uri}
この呼び出しにより、シングル サインオンの実行を可能にする Cookie を削除して、次回アプリが認証フローを開始したときに、ユーザーに再度サインインを要求するようにします。 このログアウト フローを使用しても、以前にアプリケーションに付与した内容を取り消すことにはなりません。
必須のクエリ文字列パラメーター
| パラメーター名 | 値 | 説明 |
|---|---|---|
| redirect_uri | string | 認証完了時のブラウザーの送信先になるリダイレクト URL。 これは、トークンの取得要求に使用した redirect_uri 値と正確に一致している必要があります。 |
Cookie の削除後、ブラウザーは指定のリダイレクト URL にリダイレクトされます。 ブラウザーがリダイレクト ページを読み込むときには、認証クエリ文字列パラメーターは設定されなくなり、ユーザーがログアウトされていることがわかります。
アクセス権の取り消し
Microsoft アカウントのユーザーは、Microsoft アカウント管理の同意ページにアクセスすることで、自分のアカウントに対するアプリのアクセス権を取り消しできます。
アプリに対する同意が取り消されると、以前にアプリに対して提供されたすべての更新トークンが無効になります。 新しいアクセス トークンと更新トークンを要求するための認証フローを最初から繰り返す必要があります。
関連項目
次に示すトピックでは、その他の OneDrive API に該当する大まかな概要について説明しています。