OneNote 認証と Azure AD アプリケーションのアクセス許可

適用対象 :Office 365 のエンタープライズ ノートブック

Azure AD を使用して認証する (エンタープライズ アプリ)

1. アプリケーションを登録し、クライアント ID およびシークレットを取得する
2. OneNote アプリケーションのアクセス許可のスコープを選択する
3. 管理者の同意を取得する
4. アクセス トークンを取得する
5. アクセス トークンの期限が切れた後、新しいアクセス トークンを取得する

アプリケーションを登録し、クライアント ID およびシークレットを取得する (エンタープライズ アプリ)

「アプリケーションを登録し、クライアント ID およびシークレットを取得する」を参照してください。

OneNote アプリケーションのアクセス許可のスコープを選択する (エンタープライズ アプリ)

アクセス許可のスコープは、OneNote コンテンツへのアクセスのレベルを表します。 アプリケーション アクセス許可は、組織の管理者によってアプリケーションに付与され、その組織と従業員が所有するデータへのアクセスにのみ使用することができます。 たとえば、OneNote API では、次の操作を行うためのいくつかのアプリケーション アクセス許可を公開しています。

• すべてのユーザーのノートの表示
• すべてのユーザーのノートの表示と変更

OneNote アプリケーションのアクセス許可をアプリに割り当てるには、次の手順を実行します。

1. Azure 管理ポータルで、アプリの構成ページの [他のアプリケーションに対するアクセス許可] セクションで、[アプリケーションの追加] を選択します。

2. OneNote アプリケーションを選択し、右下隅のチェック マークをクリックします。OneNote が一覧にない場合、テナントに対して OneDrive for Business をプロビジョニングしたかどうかを確認してください。

3. アプリの動作に必要な最低レベルのアプリケーション アクセス許可を選択し、変更を保存します。 複数のスコープを要求することができます。

アプリケーション アクセス許可のスコープ

アプリケーション アクセス許可を使用してノートブックにアクセスしている場合は、次のスコープから選択します。

スコープ (エンタープライズ)	Azure ポータルにおけるアクセス許可	説明
ご注意をすべてお読みください	すべてのユーザーのノートの表示	サインインしたユーザーなしで、組織内のすべてのユーザーの OneNote ノートを表示することをアプリに許可します。 アプリは、新しいノートの作成、既存のノートの変更、パスワードで保護されたセクションでのノートの表示を行うことはできません。
ご注意をすべてお読みください	すべてのユーザーのノートの表示と変更	サインインしたユーザーなしで、組織内のすべてのユーザーの OneNote ノートを表示して編集することをアプリに許可します。 アプリは、パスワードで保護されたセクションにあるノートにアクセスすることはできません。

管理者の同意を取得する

推奨:ユーザーをアプリにサインインさせる

通常、アプリケーション アクセス許可を使用するアプリを構築する場合、アプリには、管理者がアプリケーション アクセス許可を承認するページまたはビューが必要です。 このページは、アプリのサインインのフローの一部、アプリの設定の一部、または専用の "接続" フローにすることができます。 多くの場合、ユーザーが職場または学校の Microsoft アカウントでサインインした後にのみ、アプリがこの "接続" ビューを表示することが合理的です。

ユーザーをアプリにサインインさせる場合、ユーザーにアプリケーション アクセス許可の承認を求める前に、ユーザーが所属する組織を特定できます。 必ず必要というわけではありませんが、ユーザーにとってより直感的なエクスペリエンスを作成するのに役立ちます。 ユーザーをサインインさせるには、「v2.0 プロトコルのチュートリアル」に従ってください。

ディレクトリ管理者からのアクセス許可を要求する

組織の管理者からのアクセス許可を要求する準備が整ったら、管理者の同意のエンドポイントにユーザーをリダイレクトできます。 次の API 呼び出しを実行できます。

// Line breaks are for legibility only.

// Replace {tenant} with the tenant (GUID or name) you need admin consent for
// Replace {app_id} with your Azure AD assigned application id

GET https://login.microsoftonline.com/{tenant}/adminconsent?
client_id={app_id}
&state=12345
&redirect_uri=https://localhost/myapp/permissions

上記の要求をブラウザーで試すこともできます。ブラウザーのアドレス バーに次の URL を入力します (下記の手順に従って有効な URL を作成してください)。

// Replace {tenant} with the tenant (GUID or name) you need admin consent for
// Replace {app_id} with your Azure AD assigned application id

https://login.microsoftonline.com/{tenant}/adminconsent?client_id={app_id}&state=12345&redirect_uri=https://localhost/myapp/permissions

このテーブルは、前回の要求で使用するパラメーターについて説明します。

パラメーター	条件	説明
テナント	必須	アクセス許可の要求元のディレクトリ テナント。 これは、GUID またはフレンドリ名の形式で指定できます。 ユーザーが所属しているテナントがわからないときに、そのユーザーを任意のテナントでサインインさせる場合は、common を使用します。
クライアント ID	必須	アプリケーション登録ポータルでアプリに割り当てられたアプリケーション ID。
redirect_uri	必須	アプリが処理するために応答を送信するリダイレクト URI。URL でエンコードされている必要があることを除き、ポータルに登録したリダイレクト URI のいずれかに完全に一致する必要があります。また追加のパス セグメントを含めることができます。
ステート	推奨	トークン応答でも返される、要求に含まれている値。任意のコンテンツの文字列にすることができます。state は、使用していたページまたはビューなど、認証要求が発生する前の、アプリでのユーザーの状態に関する情報をエンコードするために使用されます。

続行して承認を行える管理者の同意ダイアログが表示されます。

成功応答

管理者がアプリケーションのアクセスを承認した場合、成功応答は次のようになります。

GET https://login.microsoftonline.com/{tenant}/Consent/Grant

このテーブルは、前の応答で返される値について説明します。

パラメーター	説明
テナント	要求されたアクセス許可をアプリケーションに付与したディレクトリ テナント (GUID 形式)。

エラー応答

管理者がアプリケーションのアクセス許可を承認しなかった場合、失敗応答は次のようになります。

GET https://login.microsoftonline.com/{tenant}/login

Additional technical information: 
Correlation ID: f3817dd1-8476-46c2-a81b-fdefd209f988 
Timestamp: 2017-01-18 05:36:57Z 
AADSTS90093: This operation can only be performed by an administrator. Sign out and sign in as an administrator or contact one of your organization's administrators. 

このテーブルは、前の応答で返される値について説明します。

パラメーター	説明
テナント	要求されたアクセス許可をアプリケーションに付与したディレクトリ テナント (GUID 形式)。

アプリのプロビジョニング エンドポイントから成功応答が返されると、アプリには要求した直接アプリケーション アクセス許可が付与されています。 これで、使用するリソースのトークンを要求できるようになりました。

注意

• 管理者の承認は、1 つの特定のテナントに対する 1 回限りの手順です。
• .Her のテナントを実行するアプリケーションを実行する場合に、Azure AD でのマルチ テナント型アプリケーションとして構成するのにはあります。
• アプリケーションが独自のテナントで実行されているのか、別のテナントで実行されているのかにかかわらず、管理者の同意は必須の手順です。
• アプリケーションでは、アプリケーション アクセス許可に加えて代理アクセス許可を選択することができます (ただし、この場合も管理者の同意は必要です)。

アクセス トークンを取得する (エンタープライズ アプリ)

アプリケーションの必要な承認を取得したら、API のアクセス トークンの取得に進みます。

クライアント資格情報の許可を使用してトークンを取得するには、以下のような POST 要求を送信します。

// Replace {tenant} with the tenant (GUID or name) you need admin consent for
// Replace {app_id} with your Azure AD assigned application id
// Replace {app_secret} with an Azure AD generated key for your application

POST https://login.microsoftonline.com/{tenant}/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={app_id}&client_secret={app_secret}&resource=https%3A%2F%2Fonenote.com%2F

このテーブルは、前回の要求で使用するパラメーターについて説明します。

パラメーター	条件	説明
付与の型	必須	である必要があります。client_credentials
クライアント ID	必須	アプリケーション登録ポータルでアプリに割り当てられたアプリケーション ID。
クライアント シークレット	必須	アプリケーション登録ポータルでアプリ用に生成したアプリケーション シークレット。 このアプリケーション シークレットは URL でエンコードされていることが非常に重要です
リソース	必須	この要求で resource パラメーターに渡される値は、必要なリソースのリソース識別子 (アプリケーション ID の URI) である必要があります。 OneNote API では、値は https://onenote.com/ です。 この値は、アプリに対して構成したすべての直接アプリケーション アクセス許可をトークン エンドポイントに通知します。使用するリソースに関連付けられているものに対してトークンを発行する必要があります。

成功応答

成功応答は、次のようになります。

{
  "token_type": "Bearer",
  "expires_in": "3600",
  "resource": "https:\/\/onenote.com\/",
  "access_token": "eyJ0eXAiOiJKV1Qi..."
}

このテーブルは、前回の要求で使用する値について説明します。

パラメーター	説明
トークンの型	トークンの種類の値を示します。Azure AD がサポートしている種類は bearer のみです。
有効期限	アクセス トークンの有効期間 (秒単位)。
リソース	このトークンを使用できるリソースのリソース識別子 (アプリケーション ID の URI)。
アクセス トークン	要求されたアクセス トークン。 アプリは、Web API など、セキュリティで保護されたリソースへの認証にこのトークンを使用できます。

エラー応答

エラー応答は、次のようになります (この例では、client_secret の無効な値が要求で提供されました)。

{
  "error": "invalid_client",
  "error_description": "AADSTS70002: Error validating credentials. AADSTS50012: Invalid client secret is provided.\r\nTrace ID: b6e89947-f005-469e-92ad-18aed399b140\r\nCorrelation ID: c2d1c230-bee9-41f1-9d4d-a5687e01b7bc\r\nTimestamp: 2017-01-19 20:34:11Z",
  "error_codes": [
    70002,
    50012
  ],
  "timestamp": "2017-01-19 20:34:11Z",
  "trace_id": "b6e89947-f005-469e-92ad-18aed399b140",
  "correlation_id": "c2d1c230-bee9-41f1-9d4d-a5687e01b7bc"
}

このテーブルは、前回の要求で使用する値について説明します。

パラメーター	説明
エラー	発生するエラーの種類の分類と、エラーへの応答に使用できるエラー コード文字列。
エラーの詳細	認証エラーの根本原因を特定するために役立つ可能性のある詳細なエラー メッセージ。
エラーのコード	診断に役立つ可能性がある STS 固有のエラー コードの一覧。
タイムスタンプ	エラーが発生した時刻。
トレース ID	診断に役立つ可能性がある要求の一意の識別子。
相関 ID	コンポーネント全体の診断に役立つ可能性のある要求の一意の識別子。

OneNote API に対する要求にアクセス トークンを含める

OneNote API に対するすべての要求は、Authorization ヘッダー内でベアラー トークンとしてアクセス トークンを送信する必要があります。たとえば、次の要求は 5 つのノートブックを取得し、それらはアルファベット順に名前で並べ替えられます。

GET https://www.onenote.com/api/v1.0/users/foo@example.com/notes/notebooks?top=5
Authorization: Bearer {access-token}

アクセス トークンは 1 時間のみ有効であるため、その期限が切れた場合は新しいトークンを取得する必要があります。 トークンを使用する前に、その有効期限をチェックし、必要に応じて新しいアクセス トークンを取得する必要があります。 管理者は、アクセス許可を取り消さない限り、アクセス許可に再度同意する必要はありません。

アクセス トークンの期限が切れた後、新しいアクセス トークンを取得する (エンタープライズ アプリ)

アクセス トークンの期限が切れた場合、API に対する要求は 401 Unauthorized 応答を返します。アプリはこの応答を処理しなければならないため、要求を送信する前にトークンの有効期限を確認する必要があります。

前述の「アクセス トークンを取得する」セクションで説明されている処理を繰り返すことにより、新しいアクセス トークンを要求できます。

保存されたトークンを更新し、アプリが最も長い有効期限のトークンを保有するようにします。

エラー

認証でエラーが発生した場合、Web ブラウザーはエラー ページへとリダイレクトされます。エラー ページでは、エンドユーザーにわかりやすいメッセージが表示されますが、そのページの URL には問題を解決するのに役立つ追加パラメーターが含まれます。この URL パラメーターはブックマークとして含まれています。たとえば、#error={error_code}&error_description={message} です。 #error={error_code}&error_description={message}

管理者がアプリケーションに同意しないことにした場合、フローはリダイレクト URL にリダイレクトされ、エラー パラメーターが含められます。

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

関連項目

• OneNote の開発
• OneNote API で開発する
• OneNote デベロッパー センター
• OneNote の開発者ブログ
• Stack Overflow 掲載の OneNote の開発に関する質問
• OneNote GitHub のリポジトリ