@apigrate/ms-graph-api

Apigrate MS Graph API Connector

This is a simple NodeJS API connector supporting basic capabilities for working with the Microsoft Graph API.

Getting Started

Please note this connector makes use of isomorphic fetch polyfill to ensure consistency with the Fetch API. Make sure it is installed as a peer dependency.

Instantiate the connector like this:

const { MSGraphConnector } = require('@apigrate/ms-graph-api');
const client = new MSGraphConnector({
  client_id:     process.env.MSGRAPH_CLIENT_ID, 
  client_secret: process.env.MSGRAPH_CLIENT_SECRET, 
  redirect_uri:  process.env.MSGRAPH_AUTH_REDIRECT_URI, 
  tenant:        process.env.MSGRAPH_TENANT_TYPE, 
  credentialHandler
});

See Microsoft's documentation for more information about the client_id, client_secret, redirect_id and tenant values.

The Credential Handler

The credentialHandler is an object responsible for getting and setting Oauth credentials to/from persistent storage; you must implement it yourself. It does not directly call any Microsoft APIs, but its methods will be invoked when the connector detects changes to access or refresh tokens. Implement it by following this signature:

let credentialHandler = {
  /** Invoked when the client needs credentials for an API call. */
  getCredentials: async ()=>{
    return await myCredentialStorageImplementation.get();
  },
  
  /** Invoked when the client has received an update to the credentials. Save the credentials in persistent storage here. */
  putCredentials: async (credentials)=>{
    try{
      debug('Storing updated credentials...');
      await myCredentialStorageImplementation.set(credentials);
      debug('...success.');
    }catch(ex){
      debug('Error Storing credentials. '+ ex.message)
      console.error(ex);
    }
  }
};

OAuth Support

You can use the connector to assist in the OAuth authorization process. To assemble a URL for beginning an OAuth dialog, use the connector like this:

const { getAuthorizationUrl } = require('@apigrate/ms-graph-api');

let scope = "offline_access user.read files.read";
let state = "persistentStateToCheckOnCallback";

let url = getAuthorizationUrl(
  process.env.MSGRAPH_CLIENT_ID,
  process.env.MSGRAPH_AUTH_REDIRECT_URI, 
  process.env.MSGRAPH_TENANT_TYPE, 
  scope, 
  state);

// redirect to this url to begin OAuth prompts...

Obtaining an Access Token for a code

Instantiate a client as in Getting Started above. Then...

// code = the code received from the MSGraph OAuth callback (typically on an HTTP request).

let credentials = await client.getAccessToken(code);

// ... the credentialHandler will automatically store the credentials into persistent storage if the code is successfully exchanged for an access token. 

Calling the Graph API

To call the Microsoft Graph API, instantiate the connector and use the graph API URL:

await client.api({ method: "GET", url: `/me` );

Keep in mind the api() method is really just a wrapper around the fetch API. Using this method automatically handles access token and refresh token activity for you (again, make sure you are using a credentialHandler to store/retrieve this data).

For different API calls, use the following properties of the parameter.

• method: string GET, PUT, POST, or DELETE
• url: string Graph API Url beginning with a '/' (relative to the base Micrsoft Graph URL)
• query: object containing any query parameters
• payload: object containing the payload for a POST or PUT request
• options: object, including headers property hash if you need to send specific headers