Last week I was asked, by two unrelated people working on two unrelated projects, for help with getting started with custom applications accessing Microsoft 365 content.
Different target resources, different programming languages, but in principle... it's the same question.
I decided that universe is giving me a sign. It's time to write a "Getting started".
Getting started
When building custom solutions that run on-premise and connect to Microsoft 365 resources (e.g. SharePoint or, Exchange), you need to execute the same sequence of steps, irrespective of software type you are building.
If you haven't already, consider joining the Microsoft 365 Developer Program. It will provide you with your own tenant in Microsoft Cloud, including access to Azure and a Microsoft 365 subscription, enabling you to build and test your applications without delay.
Should you choose to use your organization's tenant instead, you will rely on the tenant administrator to handle app registrations and grant the necessary API permissions. In such cases, plan your tasks accordingly, as this could result in additional delays.
Read more: Set up a Microsoft 365 developer sandbox subscription | Microsoft Learn
Create App registration
App registration is needed for your on-premise custom solution if it integrates with Microsoft 365 services, as it allows secure authentication and access to cloud-based APIs. It enables your application to obtain necessary permissions and interact with Microsoft services like SharePoint or Outlook. Without it, your solution cannot authenticate or securely access these resources.
I have my own developer tenant
Quickstart: Register an application with the Microsoft identity platform
Or
Use the Microsoft Graph quick start to automatically create an app registration, generate code sample in the language if your choice, and configure it with the required settings.
I'm using my organization's tenant
Contact your Service Desk and request creation of an App Registration, providing:
- a short description of the software you are building,
- a name and department of a person who will be main contact,
- API Permissions your application needs and
- Redirect URLs (the URL of your application)
If you don't know which API Permissions you need, it's probably better if you start with your own developer tenant. This will allow you to evaluate your requirements and find the minimum required permissions.
In order to authenticate, you will need the client Id and secret /certificate of the app registration.
Either make sure you will be assigned as its owner or request the secret / provide certificate when making the request.
Use Postman collection to test your configuration
If you don't have experience with accessing Microsoft Graph resources from your code, it may be beneficial to isolate the problem. Use Postman collection for Microsoft Graph API to simplify testing and exploring API requests without needing to write codes. It provides pre-configured requests and examples, helping you learn how the API works and how to structure your own queries.
Important: To avoid disclosing confidential information (client id, tenant id, secrets) do NOT fork this collection to a public workspace.
Follow the Use Postman with the Microsoft Graph API procedure to fork the collection and configure your app registration for access from Postman.
Set up Authentication
The application can use delegated access, acting on behalf of a signed-in user, or app-only access, acting only as the application's own identity.
With delegated permissions the application acts on a user's behalf, it will never be able to access anything the signed in user themselves couldn't access.
With application (app-only) permissions, the application will be able to access any data that the permission is associated with, without a signed-in user present.
If you are using Postman collection for Microsoft Graph API, set up Delegated or Application authentication.
Choose Delegated folder If your application acts on behalf of a signed-in user, and the Application folder if it needs to access resources independently of a user.
If you are ready to start coding, use the Microsoft Authentication Library (MSAL) library to authenticate. If you prefer to use a library other than the Microsoft Authentication Library (MSAL) or another Microsoft-supported library, choose one with a certified OpenID Connect implementation.
If you receive "401 Unauthorized", don't worry. You've been authenticated. In the next steps, you will assign required permissions.
Set up permissions (Authorization)
Always follow the principle of least privilege. Review the Microsoft Graph REST API v1.0 endpoint reference to find the minimum required permissions your application requires.
The Microsoft Graph permissions reference provides a list of all Graph API permissions, allowing you to easily compare them.
If you are using Postman collection for Microsoft Graph API, click on the folder representing resources you want to access (e.g. SharePoint, Mail, Events, etc). The Overview tab provides you with links to the resource's documentation. The linked "Microsoft Graph v1.0" documentation helps you determine which API Permissions are required by your application.
You may also use Graph Explorer to evaluate the queries you want to implement. The "Modify permissions" tab displays a list of API permissions that are required to run the query. Always choose the least privileged permission.
The Microsoft Graph REST API v1.0 endpoint reference provides a list of all Graph APIs, grouped by a resource. Each API includes "Permissions" section listing required API permissions for delegated and app-only access. Always choose the minimum required permissions.
Once you are ready, grant your App Registration (created in Step "Create App registration") the permissions it requires.
I have my own developer tenant
Quickstart: Configure a client application to access a web API
I'm using my organization's tenant
Either contact your Service Desk and request for the required API permissions to be assigned to your App Registration.
You may also assigned them yourself, following the Add permissions to access your web API procedure, but you will need to ask the tenant's Global Administrator to approve them.
Special considerations
Accessing SharePoint
Composing the URL
When accessing SharePoint sites with Microsoft Graph API , you may build the request URL using either site Id (which may be more difficult to acquire, but cannot be changed), or URL (which is probably easier but may be changed by SharePoint Administrator upon user's request).
Using site id
GET https://graph.microsoft.com/v1.0/sites/{hostname},{spsite-id},{spweb-id}/
GET https://graph.microsoft.com/v1.0/sites/{hostname}
GET https://graph.microsoft.com/v1.0/sites/{hostname},{spsite-id}
GET https://graph.microsoft.com/v1.0/sites/{spsite-id}
Using site URL
GET https://graph.microsoft.com/v1.0/sites/{hostname}:/{site-server-relative-url}
GET https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/teams/hr/benefits
See more: Note for existing SharePoint developers
Granular permissions
See the Overview of Selected permissions in OneDrive and SharePoint for information about granular scopes that allow granting API permissions on the level of specific site, list, list item or document. Keep in mind that although the Sites.Selected is available productively since a few years now, the list, listItem, and driveItem permissions are still in beta.
If you decide to use granular permissions, apart from granting the Sites.Selected API permissions to the App Registration, you will also need to assign the application one of the four roles for a given SharePoint site.
I have my own developer tenant
Controlling app access on a specific SharePoint site collections is now available in Microsoft Graph
I'm using my organization's tenant
Contact your service desk and ask for:
-
Sites.SelectedAPI permissions to be granted to your app registration - a specific role to be assigned to the service principal for your SharePoint site
App-only access to Exchange mailbox
If you are implementing a "daemon" application that requires Application API permissions to Exchange mailboxes, you need to use RBAC for Exchange Online Mailboxes instead of API Permissions.
Graph for Exchange does not offer granular API permissions, and most probably, you won't be granted Calendars.Read or Calendars.ReadWrite to all users' calendars.
Code libraries
Authentication with MSAL
The Microsoft identity platform supports authentication for architectures are based on the industry-standard protocols OAuth 2.0 and OpenID Connect. By using the authentication libraries for the Microsoft identity platform, your application will authenticate and acquire tokens to access protected APIs.
If you can, use the Microsoft Authentication Library (MSAL) library. It support many different application architectures and platforms:
For PowerShell solutions, although there is no official PowerShell module or wrapper for MSAL libraries, you may still benefit from
- Microsoft Graph PowerShell SDK
- Azure PowerShell SDK If you prefer to use a library other than the Microsoft Authentication Library (MSAL) or another Microsoft-supported library, choose one with a certified OpenID Connect implementation.
Access Microsoft 365 resources with Graph SDK
Microsoft publishes ready-to-use SDKs for accessing Microsoft Graph APIs in many popular programming languages including
See Install a Microsoft Graph SDK for instructions.
Limit package size with Kiota
However, due to the size and scope of the Microsoft Graph REST API, these libraries are fairly large. For applications where overall installation size is a concern, this large size raises a concern.
If the application only uses a subset of Microsoft Graph, generating a custom API client with Kiota, that targets only the parts of Microsoft Graph used by your application can reduce the overall installation size of your app. See Considerations for using generated clients vs Microsoft SDKs.
Graph Toolkit for UI
Microsoft Graph Toolkit is a collection of reusable, framework-agnostic web components and authentication providers for accessing and working with Microsoft Graph. The components are fully functional right of out of the box, with built-in providers that authenticate with and fetch data from Microsoft. Microsoft Graph Toolkit is great for implementing:
- Web app
- Microsoft Teams tab
- Progressive Web App (PWA)
- Electron app
- SharePoint web part
Additional resources
Authentication flow support in MSAL
Top comments (1)
Solid gold like all your posts 🔥