OneNote の認証とアクセス許可

[アーティクル]
11/18/2015

適用対象: OneDrive のコンシューマーノートブック | Office 365 のエンタープライズノートブック

OneNote では、OneNote ノートブックへのセキュリティで保護されたアクセスを提供するために Microsoft アカウント (以前の Live Connect) および Azure Active Directory を使用します。ノートブックにアクセスする前に、まず Microsoft アカウントまたは Azure AD を使用して認証し、アクセストークンを取得する必要があります。

OneDrive のコンシューマーノートブックにアクセスするためには Microsoft アカウントが使用され、Office 365 のエンタープライズノートブックにアクセスするためには Azure AD が使用されます。

どちらの承認サービスも、OneNote との対話操作のために必要なアクセストークンを提供するために OAuth 2.0 プロトコルを実装しています。OneNote API に対するすべての要求は、Authorization ヘッダーに有効なアクセストークンを含める必要があります。

この記事では、認証に関連するプロセスのうち、ユーザーのアクションが必要な部分について説明します。クライアント ID を取得するためにアプリを登録し、必要なアクセス許可を指定し、承認サービスを呼び出してユーザーのサインインを行い、アクセストークンを取得します。

プラットフォームによっては、SDK を使用して認証フローを簡略化できる場合があります。

注意

OneNote は今後、単一の認証モデルおよび v2.0 アプリモデルによるアプリ登録をサポートする予定です。関連する最新ニュースに関しては OneNote 開発者ブログをご覧ください。

API を試してみる

この記事の手順に従って、Fiddler など自分のお気に入りのネットワークツールを使用してアクセストークンを取得します。

アプリケーションを登録し、クライアント ID とシークレットを取得する (コンシューマーアプリ)

開始するには、アプリケーションを Microsoft に登録する必要があります。このプロセスでは、アプリからリンクするサービスプリンシパルを作成し、承認サービスに送信するクライアント ID およびシークレットを生成します。

アプリがコンシューマーノートブックのみにアクセスする場合、またはコンシューマーノートブックおよびエンタープライズノートブックの両方にアクセスする場合に、これを行ってください。

Microsoft アカウントで、Microsoft アカウントデベロッパーセンターにサインインします (Windows ストアアプリを開発している場合は、代わりにこちらの方法で進めてください)。

Microsoft アカウントをお持ちでない場合は、作成する必要があります。定期的にチェックするメールアドレスを使う必要があります。おすすめのアプリページでアプリをハイライトするため、またはアプリから予期しないネットワークトラフィックが届いた場合に、ご連絡を差し上げる場合があります。迷惑メールを送ったり、個人情報を販売したりすることはありません。
[アプリケーションの作成] を選択します。
アプリへのアクセス許可を付与するようにユーザーに求めるときに表示する名前を入力し、アプリの優先言語を選択します。
使用条件とプライバシーおよび Cookie ポリシーに同意する場合は、[同意] を選択して登録を続けます。
API 設定ページで、アプリの種類を選択し、アプリに関する情報を提供します。

Web アプリケーション (サーバー側アプリ)

a.モバイルまたはデスクトップクライアントアプリの場合は、[いいえ] を選択してください。

b.ターゲットドメインに関して、サービス URL を入力します。

c.認証が完了し、アプリへのアクセス許可を付与した後にユーザーが移動するリダイレクト URL を入力します。

ネイティブアプリケーション (デバイスにインストールされたもの)

a.モバイルまたはデスクトップクライアントアプリの場合は、[はい] を選択してください。

b.(オプション) ターゲットドメインに関して、モバイルサービス URL を入力します。

c.(オプション) リダイレクト URL に関して、有効な URL を入力します。これはアプリのための識別子として機能します。物理的なエンドポイントである必要はありません。*
アプリ設定ページで表示されるクライアント ID およびクライアントシークレット、および入力している場合はリダイレクト URL を保存します。

Windows ストアアプリ

Windows アプリを作成している場合、代わりにアプリケーションを Windows デベロッパーセンターに登録します。これによりパッケージ ID (パッケージ SID) が提供され、クライアント ID の代わりに使用することになります。

Microsoft アカウントで Windows デベロッパーセンターにサインインします。
ダッシュボードで、[新しいアプリの作成] を選択し、アプリ名を入力します。
Visual Studio で、Windows ストアアプリプロジェクトを右クリックし、[ストア]、[アプリケーションをストアと関連付ける] の順に選択します。
[アプリケーションをストアと関連付ける] ウインドウで、Microsoft アカウントでサインインし、アプリを選択し、[次へ]、[関連付ける] の順に選択します。これにより、必要な Windows ストア登録情報がアプリケーションマニフェストに追加されます。
ユニバーサル Windows アプリに関しては、Windows Phone プロジェクトのための前述の 2 つのステップを繰り返します。

OneNote のアクセス許可のスコープを選択する (コンシューマーアプリ)

アクセス許可のスコープは、OneNote コンテンツへのアクセスのレベルを表します。アプリに必要なアクセス許可を要求し、ユーザーはアプリにサインインするときにアクセス許可を付与または拒否します。ユーザーは、保有するアクセス許可のみを付与することができます。

アプリの作業に必要な最低レベルのアクセス許可を選択します。複数のスコープを要求することができます。

スコープ (コンシューマー)	説明
office.onenote_create	ユーザーの OneNote ノートブックの一覧を表示して新しいページを作成することはできますが、既存のページを表示したり編集することはできません。ユーザーのノートブックの階層を列挙し、任意の場所にページを作成できます。
office.onenote_update_by_app	アプリによって作成されるすべてのページの作成、表示、および変更ができます。
office.onenote_update	ユーザーの OneNote のノートブックとページのすべてのコンテンツの作成、表示、および変更ができます。
office.onenote	OneNote のノートブックとページの表示ができますが、変更はできません。
wl.signin	Microsoft アカウントのアクセス許可のスコープアプリケーションによるシングルサインオン機能の利用を許可します。
wl.offline_access	Microsoft アカウントのアクセス許可のスコープユーザーがアクティブでないときでも、アプリケーションがオフラインで作業ができるように、更新トークンの受信を許可します。このスコープはトークンフローでは使用できません。

Office 365 のノートブックにアクセスするためのアクセス許可については、「OneNote のアクセス許可を選択する (エンタープライズアプリ)」をご覧ください。

ユーザーをサインインさせ、アクセストークンを取得する (コンシューマーアプリ)

アプリは承認サービスに接続してサインインプロセスを開始します。ユーザーがまだサインインしていない、またはまだ同意していない場合、サービスはユーザーに対して認証情報の入力およびアプリが要求しているアクセス許可への同意を求めます。認証および承認が成功した場合、OneNote API に対する要求に含めるアクセストークンを受け取ります。

重要

アクセストークンおよび更新トークンは、ユーザーのパスワードの場合と同様に、安全な方法で扱ってください。

注意

プラットフォームによっては、SDK を使用して認証フローを簡略化できる場合があります。

認証フローを選択します。どちらも標準の OAuth 2.0 フローです。

フロー	説明
トークンフロー	一度の呼び出しでアクセストークンを取得します。すばやくアクセスするのに有効ですが、長期的なアクセスに必要な更新トークンが提供されません。これは暗黙的フローとも呼ばれます。
コードフロー	最初の呼び出しにおいて認証コードを取得し、2 回目の呼び出しでそのコードとアクセストークンを交換します。wl.offline-access アクセス許可スコープと共に使用する場合、アプリは長期的なアクセスを可能にする更新トークンを受け取ります。これは認証コードフローとも呼ばれます。

フロー

説明

トークンフロー

一度の呼び出しでアクセストークンを取得します。すばやくアクセスするのに有効ですが、長期的なアクセスに必要な更新トークンが提供されません。

これは暗黙的フローとも呼ばれます。

コードフロー

最初の呼び出しにおいて認証コードを取得し、2 回目の呼び出しでそのコードとアクセストークンを交換します。wl.offline-access アクセス許可スコープと共に使用する場合、アプリは長期的なアクセスを可能にする更新トークンを受け取ります。

これは認証コードフローとも呼ばれます。

トークンフローでユーザーをサインインさせる

Web ブラウザーまたは Web ブラウザーコントロールで、以下の URL 要求を読み込みます。

GET https://login.live.com/oauth20_authorize.srf
  ?response_type=token
  &client_id={client_id}
  &redirect_uri={redirect_uri}
  &scope={scope}

必須のクエリ文字列パラメーター	説明
response_type	使用している認証フローの種類。この場合は、token。
client_id	アプリケーション用に作成されたクライアント ID。
redirect_uri	アプリケーション用に登録したリダイレクト URL。これを指定していないモバイルおよびデスクトップアプリは、次のものを使用できます: `https://login.live.com/oauth20_desktop.srf`
スコープ	アプリケーションで必要となるスコープ。例: office.onenote%20wl.sign-in

認証および承認が成功すると、Web ブラウザーはリダイレクト URL へリダイレクトを行い、アクセスパラメーターを URL に追加します。次の例に示すように、パラメーターには アクセス _トークン と トークン_型が含まれます。アクセストークンは、expires_in プロパティによって指定された秒数だけ有効です。

https://your-redirect-url
  #access_token=EwB4Aq...%3d
  &token_type=bearer
  &expires_in=3600
  &scope=office.onenote wl.signin
  &user_id=c519ea026ece84de362cfa77dc0f2348

コードフローでユーザーをサインインさせる

コードフローにおいて、アクセストークンの取得は 2 段階の手順で行われます。

ユーザーをサインインさせ、認証コードを取得します。
コードをアクセストークンと交換します。

手順 1. ユーザーをサインインさせ、認証コードを取得します。サインインプロセスを開始するために、Web ブラウザーまたは Web ブラウザーコントロールで以下の URL 要求を読み込みます。

https://login.live.com/oauth20_authorize.srf
  ?response_type=code
  &client_id={client-id}
  &redirect_uri={redirect-uri}
  &scope={scope}

必須のクエリ文字列パラメーター	説明
response_type	使用している認証フローの種類。この場合は、code。
client_id	アプリケーション用に作成されたクライアント ID。
redirect_uri	アプリケーション用に登録したリダイレクト URL。これを指定していないモバイルおよびデスクトップアプリは、次のものを使用できます: `https://login.live.com/oauth20_desktop.srf`
スコープ	アプリケーションで必要となるスコープ。例: office.onenote wl.signin wl.offline_access

次の例が示すように、認証および承認が成功すると、Web ブラウザーはリダイレクト URL へリダイレクトを行い、URL にコード パラメーターを付加します。手順 2 で使用するために、コードの値をコピーします。このコードは、数分間有効です。

https://your-redirect-uri
  ?code=M57010781-9e8c-e31e-ca0d-46bc104236c4

手順 2. 認証コードをアクセストークンおよび更新トークンと交換します。適切にエンコードされた URL 文字列をメッセージ本文に記載した次の HTTP 要求を送信します。

POST https://login.live.com/oauth20_token.srf
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id={client-id}
&client_secret={client-secret}
&code={code}
&redirect_uri={redirect-uri}

必要な本文パラメーター	説明
grant_type	要求の許可の種類。この例では、authorization_code。
client_id	アプリケーション用に作成されたクライアント ID。
client_secret	アプリケーション用に作成されたクライアントシークレット。
code	前の手順で URL パラメーターとして受け取ったコード。
redirect_uri	アプリケーション用のリダイレクト URL。これは、最初の要求における redirect_uri と一致する必要があります。

成功した場合、次の例に示すように、応答には、wl.offline_access スコープを要求した場合は、access_token と refresh_token の入った JSON 文字列が含まれます。アクセストークンは、expires_in プロパティによって指定された秒数だけ有効です。

{
  "token_type":"bearer",
  "expires_in":3600,
  "scope":"office.onenote wl.sign-in wl.offline-access",
  "access_token":"EwCAAq...wE=",
  "refresh_token":"MCvePE...$$",
  "user_id":"c519ea026ece84de362cfa77dc0f2348"
}

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

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

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

アクセストークンは 1 時間のみ有効であるため、その期限が切れた場合は新しいトークンを取得する必要があります。トークンを使用する前に、その有効期限をチェックし、必要に応じて新しいアクセストークンを取得する必要があります。ユーザーはサインインした状態を保持することができ、サインアウトする場合やアクセス許可を取り消す場合を除き、アクセス許可に再度同意する必要はありません。

アクセストークンの期限が切れた後、新しいアクセストークンを取得する (コンシューマーアプリ)

更新トークンを使用するか、または認証手順を最初から再度行うことによって新しいアクセストークンを要求することができます。

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

適切にエンコードされた URL 文字列をメッセージ本文に記載した次の HTTP 要求を送信します。

wl.offline_access アクセス許可を要求し、コードフローを使用した場合、更新トークンを受け取ります。

POST https://login.live.com/oauth20_token.srf
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id={client-id}
&client_secret={client-secret}
&redirect_uri={redirect-uri}
&refresh_token={refresh-token}

必要な本文パラメーター	説明
grant_type	要求の許可の種類。この例では、refresh_token。
client_id	アプリケーション用に作成されたクライアント ID。
client_secret	アプリケーション用に作成されたクライアントシークレット。
redirect_uri	アプリケーション用のリダイレクト URL。これはトークンを取得するために使用した redirect_uri と一致する必要があります。
refresh_token	以前に受信した更新トークン。

成功した場合、次の例に示すように、POST 要求に対する応答には、access_token と refresh_ token の入った JSON 文字列が含まれます。

{
  "token_type":"bearer",
  "expires_in": 3600,
  "scope":"office.onenote wl.sign-in wl.offline-access",
  "access_token":"EwB4Aq...wE=",
  "refresh_token":"MCVw8k...$$",
  "user_id":"c519ea026ece84de362cfa77dc0f2348"
}

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

ユーザーをサインアウトする (コンシューマーアプリ)

ユーザーをサインアウトするには、次の手順を実行します:

受信または保存しているすべてのキャッシュアクセストークンまたは更新トークンを削除します。
アプリケーションにおいてすべてのサインアウト操作を実施します (たとえば、ローカルの状態のクリーンアップ、すべてのキャッシュアイテムの削除等)。
この URL を使用して承認サービスを呼び出します。

https://login.live.com/oauth20_logout.srf
  ?client_id={client_id}
  &redirect_uri={redirect_uri}

この呼び出しは、シングルサインオンを有効にするすべての Cookie を削除し、ユーザーがサインインを要求されるようにします。

必須のクエリ文字列パラメーター	説明
client_id	アプリケーション用に作成されたクライアント ID 値。
redirect_uri	アプリケーション用のリダイレクト URL。これはトークンを取得するために使用した redirect_uri と一致する必要があります。

Cookie を削除した後、ブラウザーはリダイレクト URL へのリダイレクトを行います。リダイレクトページは、認証クエリ文字列オプションを指定することなく読み込まれます。このことはユーザーがログアウトしたことを意味します。

アクセス権を取り消す

ユーザーは Microsoft アカウントの管理ページから、アプリケーションのアカウントへのアクセス権を取り消すことができます。

アプリに関する同意が取り消された場合、以前にアプリに対して提供されたすべての更新トークンは無効となります。トークンを更新しようとすると、次の応答を受け取ります。

{
  "error":"invalid_grant",
  "error_description":"The request was denied because one or more scopes requested are unauthorized or expired. The user must first sign in and grant the client application access to the requested scope."
}

新しいアクセスおよび更新トークンを要求するために、認証フローを最初から再度行う必要があります。

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

アプリケーションで (代理のアクセス許可ではなく) アプリケーションのアクセス許可を使用する場合には、「OneNote 認証と Azure AD アプリケーションのアクセス許可」をご覧ください。

アプリケーションを登録し、クライアント ID およびシークレットを取得する
OneNote のアクセス許可を選ぶ
ユーザーをサインインさせ、アクセストークンを取得する
アクセストークンの期限が切れた後、新しいアクセストークンを取得する

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

アプリがエンタープライズノートブックのみにアクセスする場合、またはコンシューマーノートブックおよびエンタープライズノートブックの両方にアクセスする場合に、これを行ってください。

Office 365 サブスクリプションに関連付けられた Azure AD テナントにアプリを登録するには、次の作業が必要です。

Office 365 テナントへのグローバル管理者のアクセス許可を持つ Office 365 アカウントを取得する

Office 365 Developer サブスクリプションをお試しいただくか、ご購入いただけます。あるいは、条件に合うプランをサブスクライブできます。
テナント用に OneDrive for Business をプロビジョニングする

これにより、OneNote アプリケーションが利用可能になるため、OneNote のアクセス許可を指定することができます。 OneDrive for Business がプロビジョニングされているかどうかをチェックするため、Office 365 の資格情報 (someone@example.com または someone@example.onmicrosoft.com のような職場または学校アカウント) で OneNote Online にサインインします。

ノートブックが表示されたら、これで設定は完了です。"申し訳ございません。現在、ノートブックを取得できません..." と表示された場合、[マイアカウントへ移動] > [次へ] を選択します。OneDrive for Business ページが読み込まれたら、OneNote Online に戻って最新の情報に更新し、プロビジョニングを完了します。

注意

ユーザーのノートブックにアクセスする前に、ユーザーの個人用サイトを準備する必要があります。 OneNote API では、必要に応じて、サイトの自動プロビジョンが試行されます。
Office 365 サブスクリプションを Azure サブスクリプションと関連付ける

これにより、Azure AD にアプリを登録し、管理することができます。(詳細情報)

Azure サブスクリプションがない場合は、次のセクションのオプション 1 を行います。Azure サブスクリプションがある場合は、オプション 2 を行います。

重要

有効な Office 365 のライセンスのある Office 365 アカウントが必要です。有効なライセンスのないユーザーアカウントでは、OneNote Online のノートブックを表示することができず、API によるノートブックの呼び出しも失敗します。 Office 365 の管理者は、状態の確認、ライセンスの割り当て、および割り当て解除を行うことができます。

注意

MSDN サブスクライバー:無料の Office 365 Developer サブスクリプションを利用できる場合があり、Azure 特典を利用することによりコスト削減も可能です。MSDN サブスクリプションページで特典をご確認ください。

Azure サブスクリプションを Office 365 サブスクリプションと関連付ける

オプション 1: Office 365 サブスクリプションの管理者の資格情報を使用して、Azure サブスクリプションにサインアップします。Azure サブスクリプションがない場合は、これを実行してください。このプロセスでは、サブスクリプションを関連付けます。

Office 365 管理者の資格情報 (someone@example.com または someone@example.onmicrosoft.com のような職場または学校アカウント) で、Azure 管理ポータルにサインインします。
"サブスクリプションが見つかりません" のページで、[Microsoft Azure にサインアップ] を選択します。サインアップページが読み込まれ、Office 365 サブスクリプションからの一部の情報が表示されます。このアカウントは、新しい Azure サブスクリプションのサービス管理者になります。

Office 365 サブスクリプションが試用版か、有料版かによってサインアップの方法が異なります:

試用版のサブスクリプションの場合、お支払い情報を [無料試用版] ページで入力します。有料サブスクリプションに変更しない限り、課金されることはありません。

サブスクリプション契約、プランの詳細、およびプライバシーに関する声明に同意する場合、チェックボックスをオンにして、[購入] を選択します。新しい Azure アカウントのサブスクリプションページが開きます。試用版サブスクリプションには 200 ドルのクレジットが発行され、30 日間使用できます。いつでもこのページからサブスクリプションを取り消すことができます。
有料版サブスクリプションの場合、連絡先情報を入力して、[サインアップ] を選択します。サブスクリプションが作成された後、[サービスの管理を開始する] を選択し、Azure 管理ポータルを開きます。

オプション 2: 既存の Azure サブスクリプションと Office 365 サブスクリプションを関連付けます。Azure サブスクリプションのためのサービス管理者または共同管理者としての Microsoft アカウントがある場合は、これを実行してください。このプロセスによって、Microsoft アカウントが Office 365 テナントのグローバル管理者となります。

Microsoft アカウントの資格情報 (someone@live.com など) で、Azure 管理ポータルにサインインします。
ページの下部にあるドロワーで、[新規] > [App Services] > [Active Directory] > [ディレクトリ] > [カスタム作成] を選びます。
[ディレクトリの追加] ウィンドウで、ディレクトリについて [既存のディレクトリの使用] を選択します。
[サインアウトする準備ができました] を選択し、チェックマークをクリックします。これにより、ポータルからサインアウトします。
関連付けたい Office 365 テナントのグローバル管理者の資格情報を使用して再度サインインします (someone@example.com または someone@example.onmicrosoft.com のような職場または学校アカウント)。
Azure でディレクトリを使用するかどうかを確認するメッセージが表示されたら、[続行] > [今すぐサインアウト] を選びます。
ブラウザーを閉じ、もう一度 Azure 管理ポータルを開きます。
Microsoft アカウントの資格情報で再度サインインし、ナビゲーションウィンドウ内の [Active Directory] を選択します。Office 365 のディレクトリ一覧が [ディレクトリ] タブに表示されます。

Azure 管理ポータルでアプリを登録する

Azure 管理ポータルにサインインします。Azure サブスクリプションの管理者の資格情報を使用します。
ナビゲーションウィンドウ内で、[Active Directory] を選択します。
アプリケーションを登録したいディレクトリを選択し、[アプリケーション] タブを開きます。
ページの下部にあるドロワーで、[追加]、[組織で開発中のアプリケーションを追加] の順に選択します。
アプリケーションのフレンドリ名を入力し、アプリケーションの種類を選択します:

Web アプリケーションまたは Web API (ブラウザーベースまたはサーバーアプリ)

a.Web アプリケーションまたは Web API を選択します。

b.サインオンの URL に関して、ユーザーがサインインし、アプリを使用する URL を入力します。

c.アプリ ID の URL に関して、アプリの一意識別子を入力します。これは確認済みのカスタムドメイン内にある必要があります。

d.応答 URL に関して、OAuth 2.0 要求に応えてリダイレクトする URL を入力します。これは物理的なエンドポイントである必要はありませんが、有効な URI でなければなりません。

e.アプリを外部の Azure テナントに利用可能なものとするため、[アプリケーションはマルチテナントです] で [はい] を選択します。

ネイティブクライアントアプリケーション (デバイスにインストールされたアプリ)

a.ネイティブクライアントアプリケーションを選択します。

b.OAuth 2.0 要求に応えてリダイレクトする URI を入力します。これは物理的なエンドポイントである必要はありませんが、有効な URI でなければなりません。

Web アプリの場合、Azure はクライアント ID とアプリシークレット (またはキー) の両方を生成します。ネイティブクライアントアプリケーションに関して、Azure はクライアント ID を生成します。これらの値を保存します。

アプリの登録に関する詳細な説明は、Office 365 ドキュメントをご覧ください。

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

Azure 管理ポータルで、アプリの構成ページの [他のアプリケーションに対するアクセス許可] セクションで、[アプリケーションの追加] を選択します。
OneNote アプリケーションを選択し、右下隅のチェックマークをクリックします。OneNote が一覧にない場合、テナントに対して OneDrive for Business をプロビジョニングしたかどうかを確認してください。
アプリの動作に必要な最低レベルのアクセス許可を選択し、変更を保存します。複数のスコープを要求することができます。

現在のユーザーが保有する個人用ノートブックのためのスコープ

OneDrive for Business の個人用ノートブックのみを使用する場合、次のスコープの中から選択します。

スコープ (エンタープライズ)	Azure ポータルにおけるアクセス許可	説明
Notes.Create	OneNote ノートブックにページを作成する	ノートブックおよびセクションのタイトルの表示、任意の場所における新しいページの作成ができます。既存のページの表示または編集はできません。
Notes.ReadWrite.CreatedByApp	アプリケーション専用の OneNote ノートブックアクセス	ノートブックやセクションのタイトルを表示したり、新しいページを作成したり、セクションの名前を変更したり、アプリにより作成されたページを表示/変更したりできます。他のアプリにより作成されたページやパスワードで保護されたセクションのページを表示したり、変更したりできます。
Notes.Read	OneNote ノートブックを表示する	ノートブックとセクションの内容を表示できます。新しいページの作成、既存のページの変更、パスワードで保護されたセクションへのアクセスはできません。
Notes.ReadWrite	OneNote ノートブックを表示し、変更する	ノートブックやセクションのタイトルを表示したり、すべてのページを表示/変更したり、新しいページを作成したり、セクションの名前を変更したりできます。パスワードで保護されたセクションにアクセスすることはできません。

現在のユーザーがアクセスできるサイトおよびグループノートブックのためのスコープ

SharePoint サイトのノートブックまたは統合グループのノートブックを使用している場合は、次のスコープの中から選択します。これらのアクセス許可は現在のユーザーの個人用ノートブックにも適用されますが、他のユーザーと共有している個人用ノートブックには適用されません。共有された個人用コンテンツへのアクセスは、現在サポートされていません。

スコープ (エンタープライズ)	Azure ポータルにおけるアクセス許可	説明
Notes.Read.All	組織内の OneNote ノートブックを表示する	ノートブックとセクションのコンテンツで、サインインしたユーザーにアクセス許可が与えられているコンテンツを表示できます。新しいページの作成、既存のページの変更、パスワードで保護されたセクションへのアクセスはできません。
Notes.ReadWrite.All	組織内の OneNote ノートブックを表示および変更する	サインインしているユーザーがアクセスできるすべてのノートブックにおいて、ノートブックおよびセクションのタイトルの表示、すべてのページの表示および変更、すべてのセクションの名前の変更、新しいページの作成ができます。パスワードで保護されたセクションにアクセスすることはできません。

スコープ (エンタープライズ)

Azure ポータルにおけるアクセス許可

説明

Notes.Read.All

組織内の OneNote ノートブックを表示する

ノートブックとセクションのコンテンツで、サインインしたユーザーにアクセス許可が与えられているコンテンツを表示できます。

新しいページの作成、既存のページの変更、パスワードで保護されたセクションへのアクセスはできません。

Notes.ReadWrite.All

組織内の OneNote ノートブックを表示および変更する

サインインしているユーザーがアクセスできるすべてのノートブックにおいて、ノートブックおよびセクションのタイトルの表示、すべてのページの表示および変更、すべてのセクションの名前の変更、新しいページの作成ができます。

パスワードで保護されたセクションにアクセスすることはできません。

OneDrive の個人用ノートブックにアクセスするためのアクセス許可については、「OneNote のアクセス許可を選択する (コンシューマーアプリ)」を参照してください。

ユーザーをサインインさせ、アクセストークンを取得する (エンタープライズアプリ)

重要

アクセストークンおよび更新トークンは、ユーザーのパスワードの場合と同様に、安全な方法で扱ってください。

注意

プラットフォームによっては、SDK を使用して認証フローを簡略化できる場合があります。

アクセストークンの取得は 2 段階の手順で行われます:

ユーザーをサインインさせ、認証コードを取得します。
コードをアクセストークンと交換します。

このプロセスは認証コード付与フローを表します。暗黙的フローを使用する場合、マニフェストファイルを編集する必要があります。「ブラウザーベースの Web アプリを登録する」の「OAuth 2.0 の暗黙的な付与フローを許可するようアプリケーションを構成する」をご覧ください。

次の URL では、任意のアプリケーションに対して有効である共通のテナントエンドポイントを使用します。

https://login.microsoftonline.com/common/oauth2/authorize
  ?response_type=code
  &client_id={client-id}
  &redirect_uri={redirect-uri}
  &resource=https://onenote.com/

必須のクエリ文字列パラメーター	説明
response_type	使用している認証フローの種類。この場合は、code。
client_id	アプリケーション用に作成されたクライアント ID。
redirect_uri	アプリケーション用のリダイレクト URL。
リソース	アクセスが必要なリソースこの例では、 https://onenote.com/

次の例が示すように、認証および承認が成功すると、Web ブラウザーはリダイレクト URI へリダイレクトを行い、URL にコード パラメーターを付加します。手順 2 で使用するために、コードの値をコピーします。このコードは、数分間有効です。

https://your-redirect-uri/
  ?code=AAABAA...AA
  &session_state=d56e3523-614e-4fbe-bf89-3ba0f065954b

POST https://login.microsoftonline.com/common/oauth2/token
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&client_id={client-id}
&client_secret={client-secret}
&redirect_uri={redirect-uri}
&code={code}
&resource=https://onenote.com/

必要な本文パラメーター	説明
grant_type	要求の許可の種類。この例では、authorization_code。
client_id	アプリケーション用に作成されたクライアント ID。
client_secret	Web アプリケーションおよび Web API のみアプリケーション用に作成されたクライアントシークレット。
code	前の手順で URL パラメーターとして受け取ったコード。
redirect_uri	アプリケーション用のリダイレクト URL。これは、最初の要求における redirect_uri と一致する必要があります。
リソース	アクセスが必要なリソースこの例では、 https://onenote.com/

成功した場合、次の例に示すように、応答にはaccess_token および refresh_token の入った JSON 文字列が含まれます。アクセストークンは、expires_in プロパティによって指定された秒数だけ有効となります。

{
  "token_type":"Bearer",
  "expires_in":"3600",
  "scope":"Notes.ReadWrite",
  "expires_on":"1446588136",
  "not_before":"1446584236",
  "resource":"https://onenote.com/",
  "access_token":"eyJ0eX...2-w",
  "refresh_token":"AAABAAA...IAA",
  "id_token":"eyJ0eX...fQ."
}

要求において使用可能な追加パラメーターを含むコード付与フローの Azure AD 実装の詳細については、「認証コード付与フロー」を参照してください。

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

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

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

更新トークンを使用するか、または認証手順を最初から再度行うことによって新しいアクセストークンを要求することができます。

適切にエンコードされた URL 文字列をメッセージ本文に記載した次の HTTP 要求を送信します。

次の例の URL では、任意のアプリケーションに対して有効である共通のテナントエンドポイントを使用します。

POST https://login.microsoftonline.com/common/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id={client-id}
&client_secret={client-secret}
&redirect_uri={redirect-uri}
&refresh_token={refresh-token}
&resource={resource-id}

必要な本文パラメーター	説明
grant_type	要求の許可の種類。この例では、refresh_token。
client_id	アプリケーション用に作成されたクライアント ID。
client_secret	Web アプリケーションおよび Web API のみアプリケーション用に作成されたクライアントシークレット。
redirect_uri	アプリケーション用のリダイレクト URL。
refresh_token	以前に受信した更新トークン。
リソース	アクセスが必要なリソースこの例では、 https://onenote.com/

成功した場合、次の例に示すように、POST 要求に対する応答には access_token および refresh_token の入った JSON 文字列が含まれます。

{
  "token_type":"Bearer",
  "expires_in":"3600",
  "scope":"Group.Read.All Notes.ReadWrite",
  "expires_on":"1447656020",
  "not_before":"1447652120",
  "resource":"https://onenote.com/",
  "access_token":"eyJ0eX...Jww",
  "refresh_token":"AAABAAA...IAA"
}

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

OneNote の開発のための SDK

OneNote アプリは、OneNote API に対するすべての要求に必要なアクセストークンを取得するのに OneDrive API SDK を使用することができます。 SDK は認証を簡単にします。 ID 情報を提供し、いくつかの呼び出しを統合するだけで、SDK はサインインから、トークンの取得、格納、更新への同意まですべてを処理します。それから、OneNote API への REST 呼び出しを行うことができます。 iOS チュートリアルは、SDK を OneNote アプリで使う方法を説明します。

コンシューマーノートブックの場合、すべてのバージョンの SDK は Microsoft アカウント認証をサポートします。エンタープライズノートブックの場合、一部のバージョンの SDK は Azure Active Directory もサポートします。現在サポートされるプラットフォームの一覧については、OneDrive ドキュメントをご覧ください。

注意

OneDrive API SDK は、Live SDK を置き換えます。 Live SDK は廃止されましたが、それを使用する既存の OneNote アプリケーションを引き続きサポートします。新しい開発では、OneDrive API SDK を使用してください。

ある時点で、認証の処理と OneNote API へのネイティブ呼び出しのサポートの両方を行うライブラリが提供されるかもしれませんが、今は OneDrive API SDK をお使いください。

または、エンタープライズアプリは、Active Directory Authentication Library (ADAL) を使用して、Office 365 と SharePoint ホスト型のノートブックにアクセスできます。お使いのプラットフォームで利用可能な SDK がない場合や、認証プロセスをさらに制御する場合は、ADAL を直接使用することを検討してください。 ASP.NET MVC チュートリアルは、ADAL を OneNote アプリで使う方法を説明します。

重要

OneNote コンテンツとリソースを操作するには、常に OneNote API を使う必要があります。 OneDrive API を使用しないでください。

エラー

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

ユーザーがアプリケーションに同意しない場合、フローはリダイレクト URL にリダイレクトされ、エラーパラメーターが含まれます。

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

次の方法で共有

OneNote の認証とアクセス許可

API を試してみる

Microsoft アカウントを使用して認証する (コンシューマーアプリ)

アプリケーションを登録し、クライアント ID とシークレットを取得する (コンシューマーアプリ)

Windows ストアアプリ

OneNote のアクセス許可のスコープを選択する (コンシューマーアプリ)

ユーザーをサインインさせ、アクセストークンを取得する (コンシューマーアプリ)

トークンフローでユーザーをサインインさせる

コードフローでユーザーをサインインさせる

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

アクセストークンの期限が切れた後、新しいアクセストークンを取得する (コンシューマーアプリ)

ユーザーをサインアウトする (コンシューマーアプリ)

アクセス権を取り消す

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

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

Azure サブスクリプションを Office 365 サブスクリプションと関連付ける

Azure 管理ポータルでアプリを登録する

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

現在のユーザーが保有する個人用ノートブックのためのスコープ

現在のユーザーがアクセスできるサイトおよびグループノートブックのためのスコープ

ユーザーをサインインさせ、アクセストークンを取得する (エンタープライズアプリ)

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

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

OneNote の開発のための SDK

エラー

関連項目

その他のリソース

次の方法で共有

OneNote の認証とアクセス許可

API を試してみる

Microsoft アカウントを使用して認証する (コンシューマー アプリ)

アプリケーションを登録し、クライアント ID とシークレットを取得する (コンシューマー アプリ)

Windows ストア アプリ

OneNote のアクセス許可のスコープを選択する (コンシューマー アプリ)

ユーザーをサインインさせ、アクセス トークンを取得する (コンシューマー アプリ)

トークン フローでユーザーをサインインさせる

コード フローでユーザーをサインインさせる

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

アクセス トークンの期限が切れた後、新しいアクセス トークンを取得する (コンシューマー アプリ)

ユーザーをサインアウトする (コンシューマー アプリ)

アクセス権を取り消す

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

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

Azure サブスクリプションを Office 365 サブスクリプションと関連付ける

Azure 管理ポータルでアプリを登録する

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

現在のユーザーが保有する個人用ノートブックのためのスコープ

現在のユーザーがアクセスできるサイトおよびグループ ノートブックのためのスコープ

ユーザーをサインインさせ、アクセス トークンを取得する (エンタープライズ アプリ)

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

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

OneNote の開発のための SDK

エラー

関連項目

その他のリソース

Microsoft アカウントを使用して認証する (コンシューマーアプリ)

アプリケーションを登録し、クライアント ID とシークレットを取得する (コンシューマーアプリ)

Windows ストアアプリ

OneNote のアクセス許可のスコープを選択する (コンシューマーアプリ)

ユーザーをサインインさせ、アクセストークンを取得する (コンシューマーアプリ)

トークンフローでユーザーをサインインさせる

コードフローでユーザーをサインインさせる

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

アクセストークンの期限が切れた後、新しいアクセストークンを取得する (コンシューマーアプリ)

ユーザーをサインアウトする (コンシューマーアプリ)

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

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

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

現在のユーザーがアクセスできるサイトおよびグループノートブックのためのスコープ

ユーザーをサインインさせ、アクセストークンを取得する (エンタープライズアプリ)

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

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