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

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

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

管理者の同意を取得する

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

通常、アプリケーション アクセス許可を使用するアプリを構築する場合、アプリには、管理者がアプリケーション アクセス許可を承認するページまたはビューが必要です。 このページは、アプリのサインインのフローの一部、アプリの設定の一部、または専用の "接続" フローにすることができます。 多くの場合、ユーザーが職場または学校の 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

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

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

成功応答

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

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

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

エラー応答

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

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. 

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

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

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

アプリケーションの必要な承認を取得したら、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

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

成功応答

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

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

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

エラー応答

エラー応答は、次のようになります (この例では、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"
}

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

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 のリポジトリ