In our previous blog, we have covered the basic knowledge about Microsoft Graph and Azure Active Directory Graph API. From this blog, let’s have some more knowledge about consuming Microsoft Graph APIs secured with Azure AD for SharePoint development.
SharePoint Framework (starting from v.1.4.1) can be used to consume Microsoft Graph APIs secured with Azure AD. This section of the blog gives an overview of how to consume Microsoft Graph API in a SharePoint Framework solution using custom permissions.
Let’s search users based on their name in the current tenant using Microsoft Graph API with SharePoint Framework in the below example. Here, a client-side SPFx web part is used to get the inputs from an end user and the MS Graph API is used to search a user based on the provided inputs from the end user. The searched result output contains all the matching names through Office UI Fabric component DetailsList.
Create a SharePoint Framework solution
Ensure you are using SharePoint Framework generator v.1.4.1 or later in your environment. If you are running an old version, you need to update framework version to 1.4.1 or later using below command.
npm install -g @microsoft/generator-sharepoint
- Create a new project directory named spfx-api-scopes in your favorite location by following Step 2 – To Create SPFx web part from this link.
- When scaffolding is completed, start Visual Studio code using below command.
Configure initial elements
Create custom properties to use in the client-side web part.
- Create a source code file named ClientMode.ts inside src/webparts/graphConsumer/components folder of the solution.
- Declare a TypeScript enum for ClientMode property of web part inside ClientMode.ts file.
- Inside GraphConsumerWebPart.ts file (path: \src\webparts\graphConsumer\GraphConsumerWebPart.ts), modify IGraphConsumerWebPartProps interface to include ClientMode.
- Change getPropertyPaneConfiguration() method for property-pane choice selections.
- Also, you will need to update the render method to create an instance of React component to render client mode choices.
- Add below import statements at the top of the GraphConsumerWebPart.ts file to import PropertyPaneChoiceGroup control and ClientMode enum.
Update resource strings
- Rewrite the interface in mystrings.d.ts file inside src/webparts/graphConsumer/loc folder to compile the solution.
- Update en-us.js file in the same folder to configure values for resource strings.
Apply style for client-side web part
You will need to update SCSS style file
- Add following styles in GraphConsumer.module.scss under src/webparts/graphConsumer/components folder.
Configure React component
Modify GraphConsumer component under src/webparts/graphConsumer/components folder.
- Edit IGraphConsumerProps.ts file to include the custom properties by importing ClientMode enum and WebPartContext type.
- IUserItem interface file defines users fetched from the tenant and it is inside the components folder.
- Create a new file IGraphConsumerState.ts inside components folder to add a new interface for React component. Import IUserItem interface in IGraphConsumerState.ts state file under components folder.
- Add required import statements in GraphConsumer.tsx file.
- Outline column definition for the DetailsList Office UI Fabric component after the import statements.
- Update render() method with the below code.
- Change React component type as shown below.
- Handle events for TextField component and validations for search criteria.
- Add below code to examine client technology for consuming Microsoft Graph.
Configure the API permissions requests
You need to explicitly mention the permission requirements in the solution manifest file in order to consume Microsoft Graph API.
To achieve this, configure webApiPermissionRequests in package-solution.json file under config folder
webApiPermissionRequests item defines the resource and scope of permission request. The resource can be name or Azure AD ObjectId for which to configure permission request. Microsoft Graph is the resource for consuming Microsoft Graph capabilities. The scope defines the type of the permission or its unique ID.
You can use User.ReadBasic.All permission to search users and get user properties such as displayNameand mail.
Consume Microsoft Graph
You can use two ways to consume Microsoft Graph:
- AadHttpClient client object: used to consume Microsoft Graph or any other REST API
- MSGraphClient client object: used to consume Microsoft Graph only.
AadHttpClient client object
- Call context.aadHttpClientFactory.getClient() method to create a new instance of AadHttpClient client object.
- Insert below _searchWithAad() method inside GraphConsumer class in the sample solution
MSGraphClient client object
You can utilize MSGraphClient object to target Microsoft Graph.
Insert below _searchWithGraph() method inside GraphConsumer class in the sample solution.
Deploy the solution
You’re now done to build and deploy the solution.
- Run the gulp commands to build the solution.
Bundle and package your solution.
- Upload the solution package (.sppkg file) from sharepoint/solution folder of your project directory to the app catalog of your tenant.
- Once you upload the package in “Apps for SharePoint”, a message at the bottom of the screen conveys that the package requires permissions. This is because of the webApiPermissionRequests property where we mentioned “Microsoft Graph” as a resource and “User.ReadBasic.All” as the scope in package-solution.json file. Click Deploy.
- Navigate to the SharePoint Admin Center and choose Try the preview from the upper right hand corner.
- Select API management under Advanced in the quick launch menu.
SharePoint Online admin of your tenant can approve or deny any pending permission approval request. You cannot view the solution package which requests the permission though.
- Select the permission requested inside package-solution.json file and choose Approve or reject.
- Click Approve from Approve or reject access panel to provide access.
- Once successfully approved, you are now ready to test your solution.
Test the solution
- Execute below gulp command to run your solution.
gulp serve –nobrowser
- Open the browser and navigate to the SharePoint Framework Workbench page for your tenant.
Add the newly configured GraphConsumer client-side web part.
- Set ClientMode from properties, either AadHttpClient or MSGraphClient and search for users.
Done! This way you can consume Microsoft Graph APIs in SharePoint Framework.
Using Microsoft Graph API, the Azure AD resources are accessed to provide searched users in a secure manner. Multiple APIs can be used from Office 365 and other Microsoft cloud services through a single endpoint i.e. Microsoft Graph (https://graph.microsoft.com). Microsoft Graph supports to access data from multiple Microsoft Cloud Services including Azure AD, SharePoint, MS Planner, MS Teams, etc.
TatvaSoft. (2019). Microsoft Graph with SharePoint Framework. Available at: https://www.tatvasoft.co.uk/blog/microsoft-graph-with-sharepoint-framework/ [Accessed: 7th March 2019].