OneNote authentication and Azure AD application permissions

Applies to: Enterprise notebooks on Office 365

To 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 these steps 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 portal Description
Notes.Read.All View notes for all users Allows 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.All View and modify notes for all users Allows 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.

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 the following:

// 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=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 these instructions).

// 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=http://localhost/myapp/permissions

This table describes the parameters used in the previous request:

Parameter Condition Description
tenant Required The 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_id Required The Application ID that the Application Registration Portal assigned to your app.
redirect_uri Required The 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.
state Recommended A 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

This table describes the values returned in the previous response:

Parameter Description
tenant The 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. 

This table describes the values returned in the previous response:

Parameter Description
tenant The 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.

Note

  • Administrator consent is a one-time step for a specific tenant.
  • If you want your application to run .her tenants, you have to configure it as a multi-tenant application in Azure AD.
  • Whether the application is running in its own tenant or another tenant, administrator consent is a required step
  • 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 the following:

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

This table describes the parameters used in the previous request:

Parameter Condition Description
grant_type Required Must be client_credentials.
client_id Required The Application ID that the Application Registration Portal assigned to your app.
client_secret Required The Application Secret that you generated for your app in the app registration portal. It is very important that this is URL encoded
resource Required The 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..."
}

This table describes the values used in the previous request:

Parameter Description
token_type Indicates the token type value. The only type that Azure AD supports is bearer.
expires_in How long the access token is valid (in seconds).
resource The resource identifier (Application ID URI) of the resource this token can be used against.
access_token The 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"
}

This table describes the values used in the previous request:

Parameter Description
error An error code string that you can use to classify types of errors that occur, and to react to errors.
error_description A specific error message that might help you identify the root cause of an authentication error.
error_codes A list of STS-specific error codes that might help with diagnostics.
timestamp The time at which the error occurred.
trace_id A unique identifier for the request that might help with diagnostics.
correlation_id A 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 an access token earlier in this topic.

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.

See also