Creating an Azure AD Application with Service Principal

OneNote supports Service Principal-based authentication, which is role-based. If you wish to use a Service Principal to authenticate to OneNote you must create a custom Azure AD application as described here.

To use Azure Service Principal authentication, you must set up the ability to assign a role to the authentication application, then register an application with the Azure AD tenant to create a new Service Principal. That new Service Principal can then leverage the assigned role-based access control to access resources in your subscription.

Authenticating with an Azure Service Principal

In https://portal.azure.com:

1. In the left-hand navigation pane, select Azure Active Directory > App registrations.
2. Click New registration.
3. Enter a name for the application.
4. Select the desired tenant setup. Since this custom application is for Azure Service Principal, choose Any Microsoft Entra ID tenant - Multi Tenant.
5. To register the new application, click Register. An application management screen displays.
   Note the value in Application (client) ID as the OAuthClientId and the Directory (tenant) ID as the AzureTenant.
6. Navigate to Certificates & Secrets and define the application authentication type. There are two types of authentication available: certificate (recommended) or client secret.
   • For certificate authentication: In Certificates & Secrets, select Upload certificate, then upload the certificate from your local machine. For an example of how to create this certificate, see https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-self-signed-certificate.
   • For creating a new client secret: In Certificates & Secrets, select New Client Secret for the application and specify its duration. After the client secret is saved, OneNote displays the key value. This value is displayed only once, so record it for future use. (This value becomes the OAuthClientSecret.)

7. Navigate to the Authentication tab and select the Access tokens option.
8. Select the Microsoft Graph API, and the following delegated permissions allow access to the full functionality of the driver:
   • Read and write all Notebooks, Sections, SectionGroups and Pages.
   • Read all users.
   • Read all groups.
9. Save your changes.
10. If you have specified the use of permissions that require admin consent (such as the Application Permissions), you can grant them from the current tenant on the API Permissions page.

Granting Admin Consent

Some custom applications require administrative permissions to operate within an Azure Active Directory tenant. Admin consent can be granted when creating a new custom Azure AD application, by adding relevant permissions that are already marked with "Admin Consent Required". Admin consent is also required to use Client Credentials in the authentication flow.

To grant admin consent:

1. Have an admin log in to https://portal.azure.com.
2. Navigate to App Registrations and find the custom Azure AD application you created.
3. Under API Permissions, click Grant Consent.

This gives your application permissions on the tenant under which it was created.

Consent for Client Credentials

OAuth supports the use of client credentials to authenticate. In a client credentials authentication flow, credentials are created for the authenticating application itself. The auth flow acts just like the usual auth flow, except that there is no prompt for an associated user to provide credentials. All tasks accepted by the application are executed outside of the context of a default user.

Note: Since the embedded OAuth credentials authenticate on a per-user basis, you cannot use them in a client authentication flow. You must always create a custom Azure AD application to use client credentials.

In https://portal.azure.com:

1. Create a custom Azure AD application, as described above.
2. Navigate to App Registrations.
3. Find the application you just created, and open API Permissions.
4. Select the Microsoft Graph permissions. There are two distinct sets of permissions: Delegated and Application.
5. For use with Service Principal, specify Application permissions.
6. Select the permissions you require for your integration.

Client OAuth Flow With a Certificate

All permissions related to the client authentication flow require admin consent. This means the application embedded with the OneNote Adapter cannot be used in the client authentication flow. You must create your own OAuth application in order to use client credentials, as described above.

After your OAuth application is created:

1. Return to https://portal.azure.com.
2. Navigate to App Registration.
3. Find the application you just created.
4. Under API Permissions, select the Microsoft Graph permissions.
   There are two distinct sets of permissions: Delegated permissions and Application permissions. The permissions used during client credential authentication are under Application Permissions.
5. Select the permissions that apply to your particular integration.