Azure Active Directory を使用してサインインする - OneDrive API - OneDrive dev center

[アーティクル]
04/08/2023

Microsoft Graph の使用

このトピックでは、OneDrive 個人用の Microsoft アカウントを使用してアプリケーションを認証する方法について説明します。ただし、この方法は非推奨になっています。新しいアプリケーションは、Microsoft Graph を使用して開発して、「Microsoft Graph での OneDrive の認証とサインイン」の認証プロセスに従うようにする必要があります。

Azure Active Directory を使用した認証

OneDrive for Business で OneDrive API を使用するには、ユーザーの代わりに特定のアクセス許可のセットでアプリを認証するアクセストークンが必要になります。

OneDrive for Business にアクセスするようにアプリケーションを構成することは簡単ではありません。このプロセスを簡単にするための作業を続けています。ご理解ください。

このセクションでは、次に示す操作の方法について説明します。

Azure Active Directory にアプリを登録します。
OneDrive for Business にサインインする

OneDrive API は、標準の OAuth 2.0 認証方式を使用してユーザーを認証し、アクセストークンを生成します。アクセストークンは、API 呼び出しごとに HTTP ヘッダーで提示します。

Authorization: bearer {token}

API にアクセスするには、特定のエンドポイント URL に HTTP 要求を送信します。ルート URL は、REST エンドポイントとして機能するサーバーのホスト名に基づいています。探索サービスを使用すると、Office 365 サービスのエンドポイントを検索できます。詳細については、「探索サービス API を使用したエンドポイントの探索に関する共通タスク」を参照してください。ルート URL は、次に示す例のようになります。{tenant} は、探索されたエンドポイント URL です。

https://{tenant}-my.sharepoint.com/_api/v2.0/

Azure Active Directory にアプリを登録する

サインインするには、まず、Azure Active Directory にアプリを登録して、アプリケーションが必要とするアクセス許可を設定する必要があります。詳細については、「SharePoint Server 2016 または OneDrive for Business のアプリを登録する」を参照してください。

OneDrive for Business にサインインする

初めて OneDrive for Business にサインインする場合、アプリには次に示す値が必要になります。

Azure Active Directory (AAD) に登録したクライアント ID とキー (クライアントシークレット)
OAuth 2 認証コードフローから受け取った認証コード
OneDrive for Business API エンドポイント URL
OneDrive for Business リソースのアクセストークン
現在のアクセストークンが失効した際に追加のアクセストークンを生成するための更新トークン

次に示す手順では、これらすべての値を取得するために必要な要求について順を追って説明します。

このフローは、標準の OAuth 2.0 認証フローに従い、Web ブラウザーまたは Web ブラウザーコントロールからの呼び出しが必要です。全般的な Office 365 認証の情報については、「Office 365 アプリ認証の概念について理解する」を参照してください。ただし、OneDrive for Business API の使用に必要とされる値のすべてを取得するには、いくつかの追加手順が必要になります。

認証のコードフローは 3 段階のプロセスであり、アプリケーションの認証および承認のための呼び出しと、OneDrive API を使用するためのアクセストークン生成の呼び出しにわかれています。このプロセスでは、アプリケーションに対する更新トークンも作成および送信します。更新トークンにより、ユーザーがアプリケーションを頻繁に使用しないときに、長期間の API の使用が可能になります。

認証コードフロー図

Azure Active Directory によって生成されたアクセストークンは、それぞれ 1 つのリソースに固有のものです。 OneDrive for Business API エンドポイントを探索して、そのエンドポイントを呼び出すには、それぞれの API エンドポイント (リソース) に 1 つずつ、2 つのアクセストークンが必要になります。

1 つの更新トークンは、アプリにアクセスが許可されたエンドポイントに対する複数のアクセストークンの生成に使用できます。

手順 1. ログインして認証コードを取得する

開始するには、ブラウザーで共通の Azure Active Directory OAuth 2 エンドポイントを読み込みます。これにより、ユーザーに自分の資格情報でのログインを求めます。この URL は、共通のテナントエンドポイントを使用して、アプリケーションを検証します。

GET https://login.microsoftonline.com/common/oauth2/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}

必須のクエリ文字列パラメーター

パラメーター名	値	説明
client_id	string	アプリ用に作成されたクライアント ID。
response_type	string	Specifies the requested response type. In an authorization code grant request, the value must be code.
redirect_uri	string	認証完了時のブラウザーの送信先になるリダイレクト URL。

注: リダイレクト URI は、Azure 管理ポータルで指定したリダイレクト URL のいずれかと一致する必要があります。

応答

次の例で示すように、正常なユーザーの認証とアプリケーションの承認時に、Web ブラウザーは、追加のパラメーターが付加されたリダイレクト URL にリダイレクトされます。

https://myapp.contoso.com/myapp/callback?code=AwABAAAAvPM...

code クエリ文字列の値は、次の手順で必要になる認証コードです。

手順 2. 認証コードをトークンに交換する

code 値を受け取ったら、このコードをトークンのセットと交換できます。このセットは、さまざまな Office 365 API で認証に使用できます。コードを交換するには、Azure Active Directory のトークンエンドポイントに要求を送信します。次に例を示します。

POST https://login.microsoftonline.com/common/oauth2/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&resource={resource_id}

この要求の本文は、URL エンコードされた文字列です。次の必須パラメーターが含まれています。

パラメーター名	値	説明
client_id	string	アプリケーション用に作成されたクライアント ID 値。
redirect_uri	string	認証完了時のブラウザーの送信先になるリダイレクト URL。これは、最初の要求に含まれる redirect_uri と一致している必要があります。
client_secret	string	アプリケーション用に作成されたキー値のいずれか。
code	string	最初の認証要求で受け取った認証コード。
resource	string	アクセスするリソース。

ほとんどの場合、OneDrive for Business API エンドポイント URL は不明です。エンドポイント URL を探索するには、Office 365 探索 API を呼び出す必要があります。探索 API で認証するには、リソース https://api.office.com/discovery/ のアクセストークンを要求する必要があります。末尾に / 文字が含まれていることを確認してください。この文字が含まれていないと、探索 API へのアクセスが拒否されます。

応答

呼び出しに成功した場合の応答本文は、JSON 文字列になります。この文字列には、access_token、expires_in、および refresh_token プロパティが含まれています。

{
  "expires_in": 3600,
  "access_token":"EwCo...AA==",
  "refresh_token":"eyJh...9323"
}

注: 応答には、追加のパラメーターが含まれていることもあります。こうしたプロパティは、API の使用には必要ありません。

重要: この応答に含まれる access_token と refresh_token の値は、ユーザーのパスワードと同じように安全に取り扱ってください。

アクセストークンは、expires_in プロパティで指定された秒数だけ有効です。新しいアクセストークンは、更新トークンを使用して要求できます。それ以外の場合は、認証要求を最初から繰り返します。

手順 3. OneDrive for Business のリソース URI を探索する

さまざまなユーザーとテナントが各種の API を提供しているため、アプリでは、サインインしているユーザーの OneDrive for Business に対応する URL を探索する必要があります。そのために、アプリでは、Office 365 探索 API を使用して、アプリとサインインしているユーザーが使用できるサービスと API のエンドポイントのリストを要求できます。

リソース https://api.office.com/discovery/ 用に受け取ったアクセストークンを使用すると、探索 API に要求を送信して、使用できるサービスを把握できます。

GET https://api.office.com/discovery/v2.0/me/services
Authorization: Bearer {access_token}

パラメーター名	値	説明
access_token	string	リソース `https://api.office.com/discovery/` に対して有効なアクセストークン

応答

呼び出しに成功すると、応答本文内の JSON データには、ユーザーとアプリが使用できるサービスに関する情報が含まれます。この応答を解析することで、OneDrive for Business API のエンドポイント URL がわかります。

{
  "@odata.context": "https:\/\/api.office.com\/discovery\/v1.0\/me\/$metadata#allServices",
  "value": [
    {
      "@odata.type": "#Microsoft.DiscoveryServices.ServiceInfo",
      "capability": "MyFiles",
      "serviceApiVersion": "v2.0",
      "serviceEndpointUri": "https:\/\/contoso-my.sharepoint.com\/_api\/v2.0",
      "serviceResourceId": "https:\/\/contoso-my.sharepoint.com\/"
    }
  ]
}

注: その他のプロパティは、ServiceInfo オブジェクトで返されます。この例では、主なプロパティが切り詰められています。

ユーザーの OneDrive for Business に対応するエンドポイント URL を特定するには、value コレクションで、次に示す述語と一致する ServiceInfo オブジェクトを見つけます。

capability = "MyFiles" AND serviceApiVersion = "v2.0"

アプリでユーザーの OneDrive for Business に対して一致する ServiceInfo オブジェクトを見つけるときには、そのオブジェクトの 2 つのプロパティ serviceResourceId と serviceEndpointUri の値を保管する必要があります。これらの値は、次の手順で、新しいアクセストークンを調達して、OneDrive API を呼び出すために使用します。

手順 4. OneDrive API 呼び出すために更新トークンをアクセストークンに交換する

この時点で、アプリにはユーザーの OneDrive for Business のリソースとエンドポイント URL がわかっているため、手順 2 で受け取った更新トークンをアクセストークンに交換できるようになります。このアクセストークンは、OneDrive API で使用できます。

更新トークンを新しいアクセストークンに交換するには、次に示す要求を送信します。

POST https://login.microsoftonline.com/common/oauth2/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&resource={resource_id}

応答本文の URL エンコードされた文字列には、次に示すパラメーターが含まれています。

パラメーター名	値	説明
client_id	string	アプリケーション用に作成されたクライアント ID。
redirect_uri	string	認証完了時にブラウザーの送信先となるリダイレクト URL。これは、最初の要求で使用される redirect_uri 値と一致する必要があります。
client_secret	string	アプリケーション用に作成されたキー値のいずれか。
refresh_token	string	以前に受信した更新トークン。
resource	string	アクセスするリソース。これは、前の手順で探索した serviceResourceId の値にする必要があります。

メモリダイレクト URI は、 Azure 管理ポータルで指定したリダイレクト URI と一致する必要があります。

応答

呼び出しに成功すると、応答本文の JSON 文字列には access_token、expires_in、および refresh_token が含まれます。

{
  "expires_in": 3600,
  "access_token":"EwCo...AA==",
  "refresh_token":"eyJh...9323"
}

注: 前回保存した更新トークンの値は、その後のトークンサービスへの呼び出しで返された値に置き換えて、アプリが最新の有効期限のトークンを保持するようにします。

access_token プロパティの値は、認証済みの要求を OneDrive API に送信するために使用できるようになっています。更新トークンの詳細については、「複数のリソース用の更新トークン」を参照してください。

重要: この応答に含まれる access_token と refresh_token の値は、ユーザーのパスワードと同じように安全に取り扱ってください。

アクセストークンは、expires_in プロパティで指定された秒数 (通常は 1 時間) だけ有効です。新しいアクセストークンは、更新トークンを使用して要求します (使用可能な場合)。または、認証要求を最初から繰り返します。

アクセストークンが失効している場合、API への要求には 401 Unauthorized 応答が返されます。認証済みの要求に対して、この応答を受け取った場合は、保管しておいた更新トークンを使用して、新しいアクセストークンを生成する必要があります。

手順 5. OneDrive API に要求を送信する

アプリがユーザーの OneDrive for Business API エンドポイントに対して有効なアクセストークンを持つようになったので、OneDrive API に対して認証された要求を行うことができます。
要求を送信するには、探索 API から受け取った serviceEndpointUri の値と、トークンサービスから受け取ったアクセストークンが必要になります。

たとえば、ユーザーの OneDrive for Business の詳細を取得するために、次に示すように、/drive API パスに要求を送信できます。

GET {serviceEndPointUri}/drive
Authorization: Bearer {access_token}

エラー

認証でエラーが発生した場合、Web ブラウザーはエラーページへとリダイレクトされます。エラーページには、ユーザーにとってわかりやすいメッセージが常に表示されますが、エラーページの URL には発生した問題の解決に役立つ可能性がある追加情報が含まれています。この種の情報は、ブラウザーに表示されるエラーページの内容で示されないことがあります。

この URL には、それぞれエラーと応答の解析に使用できるクエリパラメーターが含まれています。これらのパラメーターは、常にブックマークとして (# 文字の後に) 含まれます。ページのコンテンツでは、常にユーザーに向けた一般的なエラーメッセージを表示します。

ユーザーがアプリケーションに同意を与えない場合、フローは redirect_uri にリダイレクトして、同じエラーパラメーターを含めます。

エラー処理の詳細については、「OAuth 2.0 でのエラー処理」を参照してください。

次に示すトピックでは、その他の OneDrive API に該当する大まかな概要について説明しています。

次の方法で共有

Microsoft Graph の使用

Azure Active Directory を使用した認証

Azure Active Directory にアプリを登録する

OneDrive for Business にサインインする

手順 1. ログインして認証コードを取得する

必須のクエリ文字列パラメーター

応答

手順 2. 認証コードをトークンに交換する

応答

手順 3. OneDrive for Business のリソース URI を探索する

応答

手順 4. OneDrive API 呼び出すために更新トークンをアクセストークンに交換する

応答

手順 5. OneDrive API に要求を送信する

エラー

その他のリソース

次の方法で共有

OneDrive for Business の認証とサインイン

Microsoft Graph の使用

Azure Active Directory を使用した認証

Azure Active Directory にアプリを登録する

OneDrive for Business にサインインする

手順 1. ログインして認証コードを取得する

必須のクエリ文字列パラメーター

応答

手順 2. 認証コードをトークンに交換する

応答

手順 3. OneDrive for Business のリソース URI を探索する

応答

手順 4. OneDrive API 呼び出すために更新トークンをアクセス トークンに交換する

応答

手順 5. OneDrive API に要求を送信する

エラー

関連項目

その他のリソース

手順 4. OneDrive API 呼び出すために更新トークンをアクセストークンに交換する