Exploring The Microsoft Graph Toolkit

01 October 2019 Sergei-Sergeev MS Graph, SharePoint

At the end of September 2019, Microsoft released The Graph Toolkit library.

a collection of reusable, framework-agnostic web UI components that work automatically with Microsoft Graph

It was in preview for a while, now it's in GA, thus it's a good time to start exploring what is available in this library.  

First of all, that's a set of components, which abstract a lot of things about MS Graph, authentication, UI away from a developer. It provides a very seamless interface for building UI components. UI elements are built with web components technology - which means that they are framework agnostic. You can use it with any modern JavaScript framework.

Let's explore how to use this library with a React-based single page application and with SharePoint Framework.

React

In any app, which talks to the MS Graph the first step is:

App registration

Go to your Azure AD portal and add a new app registration. You should add redirect url http://localhost:3000 (because later on, we're using create react app). By default, the graph toolkit library uses Microsoft Authentication Library for JavaScript as the core component for authentication and access token requests. That's why we should enable implicit flow in our app registration:

Also, I made my app multitenant by checking an appropriate option at the bottom of the page. If your app isn't multitenant, you should provide additional configuration for the toolkit - authority parameter. Keep that in mind. 

The next step is to add the required permissions for the app registration. The Graph toolkit has detailed information about all permissions (or scopes, since it's all about MSAL) needed for every component. Checkout Person for example. I'm going to use the Login component together with Tasks (displays a list of todos from my account):

Some permissions require admin, so you can pre-approve your permissions from the Azure AD portal. 

Scaffold a new React app with create react app

npx create-react-app my-app --typescript

The above command will scaffold a new react app with TypeScript support. 

Install the graph toolkit:

npm install @microsoft/mgt --save

At your App.tsx component add a line, which imports all components from the toolkit:

import '@microsoft/mgt';

Alternatively, you can import the required components one by one:

import '@microsoft/mgt/dist/es6/components/mgt-login/mgt-login';

Setup the graph toolkit's provider

This step is required for any application type built with the toolkit. The graph toolkit has a notion of "Providers". They are responsible for authentication and access token acquisition for MS Graph. They are also used as adapters for specific environments, where your application runs. For example, there are SharePoint, MS Teams providers. They perform the required steps to "register" the toolkit and obtain access tokens for MS Graph. MSAL provider is good for the web because it takes care of all the authentication things on the web (as said through the msal.js and implicit flow).

What's also cool, is that you can create your own custom provider and register with the toolkit. It's useful in case if you have an application and want to add the toolkit, or if you want to handle authentication in your code. 

So how to set up the MSAL provider? Simply add it to your render method:

<mgt-msal-provider client-id="d3c013d2-eeb6-45f5-ba63-4fd499489b06"></mgt-msal-provider>

Where client id is your app id from Azure AD app registration. 

Use the toolkit

Read the documentation and start using different components in your code. For example my component below

<div className="App">
        <mgt-msal-provider client-id="d3c013d2-eeb6-45f5-ba63-4fd499489b06"></mgt-msal-provider>
        <div className="data">
            <mgt-login ref="loginComponent"></mgt-login>
            <mgt-tasks data-source="todo"></mgt-tasks>
          </div>
</div>

Produces:

There is a small issue with TypeScript definitions. React with TypeScript doesn't understand web components syntax in tsx files. That is why you have to add below declarations for any component you use to make it work:

declare global {
  /* eslint-disable-next-line */
  namespace JSX {
    interface IntrinsicElements {
      'mgt-login': any;
      'mgt-person': any;
      'mgt-msal-provider': any;
      'mgt-tasks': any
    }
  }
}

SharePoint

As I mentioned there is a SharePoint provider available as well. Let's try to configure everything to work with the SharePoint Framework. 

Scaffold a new SharePoint Framework web part

When it's ready, install the toolkit: 

npm install @microsoft/mgt --save

Setup permissions

We don't need any app registrations here, still, we need some permissions to be approved, because our web part talks to MS Graph. For that purpose, we should add a list of permissions to the web part. These permissions will be approved later by an admin. Read more here - Connect to Azure AD-secured APIs in SharePoint Framework solutions.

Below are the steps needed:

1. In your package-solution.json add new webApiPermissionRequests node with all permission you need for the toolkit:

"webApiPermissionRequests": [
      {
        "resource": "Microsoft Graph",
        "scope": "Contacts.Read"
      },
      {
        "resource": "Microsoft Graph",
        "scope": "Group.Read.All"
      },
      {
        "resource": "Microsoft Graph",
        "scope": "Group.ReadWrite.All"
      },
      {
        "resource": "Microsoft Graph",
        "scope": "People.Read"
      },
      {
        "resource": "Microsoft Graph",
        "scope": "Tasks.Read"
      },
      {
        "resource": "Microsoft Graph",
        "scope": "Tasks.ReadWrite"
      },
      {
        "resource": "Microsoft Graph",
        "scope": "User.Read"
      },
      {
        "resource": "Microsoft Graph",
        "scope": "User.ReadBasic.All"
      }
    ]
  },

2. Package and upload solution to the app catalog

gulp bundle --ship 
gulp package-solution --ship

3. Approve all requested permissions from the central administration

Setup graph toolkit's provider

Again, we should set up the toolkit's provider. Fortunately, it's very simple. In your root HelloWorldWebPart.ts file add an import 

import { Providers, SharePointProvider } from '@microsoft/mgt/dist/commonjs';

And finally add an OnInit method to your web part:

  protected async onInit() {
    Providers.globalProvider = new SharePointProvider(this.context);
  }

Use the toolkit

The same way as for web, add the toolkit's components to your SharePoint Framework components: 

export default class HelloWorld extends React.Component<IHelloWorldProps, {}> {
  public render(): React.ReactElement<IHelloWorldProps> {
    return (
      <div className={ styles.helloWorld }>
        <mgt-tasks data-source="todo"></mgt-tasks>
      </div>
    );
  }
}

The result:

All samples for this post you can find here at GitHub.

What's next?

The graph toolkit was released a few days ago. There are only 7 components inside. Not a lot, but Microsoft will add more components in the future. However today you can start playing with it and start trying to adapt to your current or future applications.