Table of contents
TOC
Collapse the table of content
Expand the table of content
Last Updated: 2/8/2017

OneNote authentication and Azure AD application permissions

Applies to: Enterprise notebooks on Office 365

Authenticate using Azure AD (enterprise apps)

  1. Register your application and get a client ID and secret
  2. Choose OneNote application permission scopes
  3. Obtain administrator consent
  4. Get an access token
  5. Get a new access token after it expires

Register your application and get a client ID and secret (enterprise apps)

See Register your application and get a client ID and secret

Choose OneNote application permission scopes (enterprise apps)

Permission scopes represent levels of access to OneNote content. An application permission is granted to an application by an organization's administrator, and can be used only to access data owned by that organization and its employees. For example, the OneNote API exposes several application permissions to do the following:

  • View notes for all users
  • View and modify notes for all users

Follow the steps below to assign OneNote application permissions to your app:

  1. In the Azure Management Portal, in the Permissions to other applications section of the app configuration page, choose Add application.

  2. Choose the OneNote application, and then click the check mark in the lower-right corner. If OneNote isn't listed, make sure you've provisioned OneDrive for Business for your tenant.

  3. Choose the lowest level of application permissions that your app needs to do its work, and save your changes. You can request multiple scopes.


Scopes for application permissions

If you're accessing notebooks using application permissions, choose from the following scopes.

Scope (enterprise)Permission in Azure portalDescription
Notes.Read.AllView notes for all usersAllows the app to view the OneNote notes of all users in your organization, without a signed-in user. The app cannot create new notes, modify existing notes, or view notes under password-protected sections.
Notes.ReadWrite.AllView and modify notes for all usersAllows the app to view and modify the OneNote notes of all users in your organization, without a signed-in user. The app cannot access notes under password-protected sections.

Recommended: Sign the user in to your app

Typically, when you build an application that uses application permissions, the app requires a page or view on which the admin approves the app's permissions. This page can be part of the app's sign-in flow, part of the app's settings, or it can be a dedicated "connect" flow. In many cases, it makes sense for the app to show this "connect" view only after a user has signed in with a work or school Microsoft account.

If you sign the user in to your app, you can identify the organization to which the user belongs before you ask the user to approve the application permissions. Although not strictly necessary, it can help you create a more intuitive experience for your users. To sign the user in, follow our v2.0 protocol tutorials.

Request the permissions from a directory admin

When you're ready to request permissions from the organization's admin, you can redirect the user to the admin consent endpoint. You can make the API call such as below:

// 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

You can also try the above request in a browser, type the following URL into your browser's address bar (make a valid URL following the instructions below).

// 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

The table below describes the parameters used in the above request:

ParameterConditionDescription
tenantRequiredThe directory tenant that you want to request permission from. This can be in GUID or friendly name format. If you don't know which tenant the user belongs to and you want to let them sign in with any tenant, use common.
client_idRequiredThe Application ID that the Application Registration Portal assigned to your app.
redirect_uriRequiredThe redirect URI where you want the response to be sent for your app to handle. It must exactly match one of the redirect URIs that you registered in the portal, except that it must be URL encoded, and it can have additional path segments.
stateRecommendedA value that is included in the request that also is returned in the token response. It can be a string of any content that you want. The state is used to encode information about the user's state in the app before the authentication request occurred, such as the page or view they were on.

You will be presented with an admin consent dialog that you can go ahead and approve.

Successful response

If the admin approves the permissions for your application, the successful response looks like this:

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

The table below describes the values returned in the above response:

ParameterDescription
tenantThe directory tenant that granted your application the permissions that it requested, in GUID format.

Error response

If the admin does not approve the permissions for your application, the failed response looks like this:

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.

The table below describes the values returned in the above response:

ParameterDescription
tenantThe directory tenant that granted your application the permissions that it requested, in GUID format.

After you've received a successful response from the app provisioning endpoint, your app has gained the direct application permissions that it requested. Now you can request a token for the resource that you want.

Notes:

  1. Administrator consent is a one time step for a specific tenant
  2. If you want your application to run in other tenants, you have to configure it as a multi-tenant application in AAD
  3. Whether the application is running in its own tenant or another tenant, administrator consent is a required step
  4. Your application is allowed to choose delegate permissions in addition to application permissions (but administrator consent is still required)

Get an access token (enterprise apps)

After you've acquired the necessary authorization for your application, proceed with acquiring access tokens for APIs. To get a token by using the client credentials grant, send a POST request such as below:

// 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

The table below describes the parameters used in the above request:

ParameterConditionDescription
grant_typeRequiredMust be client_credentials.
client_idRequiredThe Application ID that the Application Registration Portal assigned to your app.
client_secretRequiredThe Application Secret that you generated for your app in the app registration portal. It is very important that this is URL encoded
resourceRequiredThe value passed for the resource parameter in this request should be the resource identifier (Application ID URI) of the resource you want. For the OneNote API, the value is https://onenote.com/. This value informs the token endpoint that of all the direct application permissions you have configured for your app, it should issue a token for the ones associated with the resource you want to use.

Successful response

A successful response looks like this:

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

The table below describes the values returned in the above response:

ParameterDescription
token_typeIndicates the token type value. The only type that Azure AD supports is bearer.
expires_inHow long the access token is valid (in seconds).
resourceThe resource identifier (Application ID URI) of the resource this token can be used against.
access_tokenThe requested access token. The app can use this token to authenticate to the secured resource, such as to a Web API.

Error response

An error response looks like this (in this example, an invalid value for client_secret is provided in the request):

{
  "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"
}

The table below describes the values returned in the above response:

ParameterDescription
errorAn error code string that you can use to classify types of errors that occur, and to react to errors.
error_descriptionA specific error message that might help you identify the root cause of an authentication error.
error_codesA list of STS-specific error codes that might help with diagnostics.
timestampThe time at which the error occurred.
trace_idA unique identifier for the request that might help with diagnostics.
correlation_idA unique identifier for the request that might help with diagnostics across components.

Include the access token in your request to the OneNote API

All your requests to the OneNote API must send the access token as a bearer token in the Authorization header. For example, the following request gets five of your notebooks, sorted alphabetically by name:

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

Access tokens are only valid for an hour, so you'll need to get fresh tokens when they expire. You should check the token's expiration before using it, and get a new access token if needed. Admins don't have to consent to permissions again unless they revoke permissions.

Get a new access token after it expires (enterprise apps)

When an access token expires, requests to the API return a 401 Unauthorized response. Your app should handle this response and check the token expiration before sending requests.

You can request a new access token by repeating the process described in the section Get a token above.

Update your stored tokens to ensure that your app has tokens with the longest lifespan.

Errors

If there are errors with authentication, the web browser is redirected to an error page. The error page presents an end-user friendly message, but the URL for the page includes additional parameters that may help you debug what happened. The URL parameters are included as a bookmark, for example: #error={error_code}&error_description={message}

If the admin chooses not to provide consent to your application, the flow will redirect to your redirect URL and include the error parameters.

For detailed information about handling errors, see Error Handling in OAuth 2.0.

Additional resources

© 2017 Microsoft