Table of contents
TOC
目次を折りたたむ
目次を展開する
最終更新日: 2017/11/10

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 ポータルにおけるアクセス許可説明
Notes.Read.Allすべてのユーザーのノートの表示サインインしたユーザーなしで、組織内のすべてのユーザーの OneNote ノートを表示することをアプリに許可します。 アプリは、新しいノートの作成、既存のノートの変更、パスワードで保護されたセクションでのノートの表示を行うことはできません。
Notes.ReadWrite.Allすべてのユーザーのノートの表示と変更サインインしたユーザーなしで、組織内のすべてのユーザーの 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 AAD assigned application id

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

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

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

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

以下の表に、上記の要求で使用するパラメーターを示します。

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

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

成功応答

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

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

以下の表に、上記の応答で返される値を示します。

パラメーター説明
tenant要求されたアクセス許可をアプリケーションに付与したディレクトリ テナント (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. 

以下の表に、上記の応答で返される値を示します。

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

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

メモ:

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

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

アプリケーションの必要な承認を取得したら、API のアクセス トークンの取得に進みます。 クライアント資格情報の許可を使用してトークンを取得するには、以下のような POST 要求を送信します。

// Replace {tenant} with the tenant (GUID or name) you need admin consent for
// Replace {app_id} with your AAD assigned application id
// Replace {app_secret} with an AAD 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

以下の表に、上記の要求で使用するパラメーターを示します。

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

成功応答

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

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

以下の表に、上記の応答で返される値を示します。

パラメーター説明
token_typeトークンの種類の値を示します。Azure AD がサポートしている種類は bearer のみです。
expires_inアクセス トークンの有効期間 (秒単位)。
resourceこのトークンを使用できるリソースのリソース識別子 (アプリケーション ID の URI)。
access_token要求されたアクセス トークン。 アプリは、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"
}

以下の表に、上記の応答で返される値を示します。

パラメーター説明
error発生するエラーの種類の分類と、エラーへの応答に使用できるエラー コード文字列。
error_description認証エラーの根本原因を特定するために役立つ可能性のある詳細なエラー メッセージ。
error_codes診断に役立つ可能性がある STS 固有のエラー コードの一覧。
timestampエラーが発生した時刻。
trace_id診断に役立つ可能性がある要求の一意の識別子。
correlation_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} です。

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

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

その他の技術情報

© 2018 Microsoft