OneNote authentication and Azure AD application permissions
Applies to: Enterprise notebooks on Office 365
To authenticate using Azure AD (enterprise apps):
- Register your application and get a client ID and secret
- Choose OneNote application permission scopes
- Obtain administrator consent
- Get an access token
- 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:
In the Azure Management Portal, in the Permissions to other applications section of the app configuration page, choose Add application.
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.
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. |
Obtain administrator consent
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 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=https://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=https://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.