When I first came across the concept of using O365 REST-based APIs such as the Graph API and the Outlook REST API, I was overwhelmed with the immense number of possibilities that could be devised from such integration. However, what was even more overwhelming was linking and understanding all the documentation surrounding Azure AD App Registrations, OAuth 2.0 and permissions. The purpose of this post is to centralize, arrange and explain the documentation, as necessary.
Understanding the Overall Picture
To consume an O365 API, the API needs to make sure that the application that is attempting to consume it is authorized to do so. A simplified flow of this process is shown below:
To perform step 1 and get the expected response as per step 2, the following topics come into play:
- Azure AD App Registration: This acts as the door for the application to communicate with AAD to get an access token. It is a service principal that you create on the AAD of your O365 tenant.
- OAuth 2.0 flows: These act as the keys to the door; they authenticate the application.
- Permissions: These are the permissions that are inside the access token and define what the application is authorized to consume from the API
Azure AD App Registration:
Depending on the type of application that you are using, you may need to set your App Registration settings differently:
- This article in the MS Graph documentation walks through the process of creating an App Registration and contains a neat table linking the possible application types with their respective essential settings: https://docs.microsoft.com/en-us/graph/auth-register-app-v2?context=graph%2Fapi%2F1.0&view=graph-rest-1.0
OAuth 2.0 Flows:
A comparison between the two Identity endpoints – V1.0 vs V2.0
Before going into the available methods of triggering the Azure AD endpoint for providing an access token (OAuth 2.0 flows), the differences between the Microsoft identity platform (v2.0) and Azure Active Directory (v1.0) need to be discussed. When reaching the authentication endpoint for AAD, it is possible to consume either the v1.0 or the v2.0. Both are supported and fully functional; however, there are several key differences including who can sign in, consent model and scoping permissions. The following article summarizes the differences between them: https://docs.microsoft.com/en-us/azure/active-directory/develop/azure-ad-endpoint-comparison
Below, you will find a list of the most commonly used flows for either endpoint.
V2.0 OAuth 2.0 Flows:
- Authorization code flow:
This flow is usually used by native apps that require the user to be prompted for their credentials. Once implemented, this flow will prompt with Azure’s sign-in page and once the correct credentials are inputted, an “authorization code” snippet is returned. This code can then be used to get an access token: https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow
- Client credentials flow:
This flow is usually used by server-side / daemon apps that do not require user interaction. This grant only requires that the credentials of the App Registration itself are used (Client ID + Client Secret): https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow
- Resource Owner Password Credentials flow (ROPC):
This flow can be used with either types of applications, native or daemon, but it is not recommended as it requires sending the user’s credentials over the network. It should only be used when the other, more secure, flows are not possible to implement. Even though this flow can be used in a daemon scenario, Microsoft does not acknowledge nor support any issues that can arise from using the flow in this fashion: https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth-ropc
V1.0 OAuth 2.0 Flows:
- Authorization code flow:
This flow has a very similar implementation to the one in V2.0 and serves the same purpose. The only notable differences are with scoping the permissions and the endpoint itself: https://docs.microsoft.com/en-us/azure/active-directory/develop/v1-protocols-oauth-code
- Client credentials flow:
In the same sense of the previous flow, this flow is similar to its counterpart in V2.0: https://docs.microsoft.com/en-us/azure/active-directory/develop/v1-oauth2-client-creds-grant-flow
Permissions are what allow the Graph API to understand what the application is authorized to access, be it anything from all mails in an organization to calendar events for the signed-in user. The main comparison needs to be made between the two types of permission: Delegated Permissions and Application Permissions. In summary, Delegated Permissions allow the application to access the permitted resources (mails, events, OneDrive files…etc) with the same permission level of the logged-in user. Respectively, Delegated Permissions are obtained through OAuth 2.0 flows that require user credentials. On the other hand, Application Permissions are obtained through the Client credentials flow and they provide access to all resources within a certain set (all mails in all mailboxes, all events for all users, all OneDrive files across an org…etc).
- An article that discusses Permissions: https://docs.microsoft.com/en-us/graph/auth/auth-concepts#microsoft-graph-permissions
- An article that discusses the permissions naming convention as well as the available Graph permissions: https://docs.microsoft.com/en-us/graph/permissions-reference
- An article that discusses consent to permissions: https://docs.microsoft.com/en-us/azure/active-directory/develop/consent-framework
- V1.0 uses the ADAL library: https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-authentication-libraries
- V2.0 uses the MSAL library: https://docs.microsoft.com/en-us/azure/active-directory/develop/reference-v2-libraries
Samples and other links
- Graph ASP.NET tutorial using MSAL: https://docs.microsoft.com/en-us/graph/tutorials/aspnet
- Graph ASP.NET sample using MSAL and Client Credentials flow: https://github.com/Azure-Samples/ms-identity-aspnet-daemon-webapp
- Getting an access token using PostMan: https://blogs.msdn.microsoft.com/softwaresimian/2017/10/05/using-postman-to-call-the-graph-api-using-azure-active-directory-aad/
- ROPC sample using PowerShell: https://developermessaging.azurewebsites.net/2019/01/02/ropc-resource-owner-password-credentials-grant-flow/
- Microsoft Graph SDK: https://docs.microsoft.com/en-us/graph/sdks/sdks-overview?context=graph%2Fapi%2F1.0&view=graph-rest-1.0
- Limiting Exchange-related Graph Application permissions to a smaller set of mailboxes: https://docs.microsoft.com/en-us/graph/auth-limit-mailbox-access?context=graph%2Fapi%2F1.0&view=graph-rest-1.0