node-red-contrib-msgraph v1.3.0

Node-RED MS Graph API Nodes

This repository contains custom Node-RED nodes to interact with the Microsoft Graph API. These nodes handle authentication, token management, and allow querying the Microsoft Graph API using Node-RED.

Nodes

• msgraph-config: Configuration node to store MS Graph API credentials and manage authentication.
• msgraph-login: Generates an authentication URL to log in to the Microsoft Graph API.
• msgraph-login-response: Handles the OAuth2 callback and exchanges an authorization code for access tokens.
• msgraph-query: Makes authenticated requests to the Microsoft Graph API.

Installation

1. Install via npm

You can install these nodes directly using npm. Run the following command in your Node-RED user directory, typically ~/.node-red:

cd ~/.node-red
npm install node-red-contrib-msgraph

2. Install via Node-RED Palette Manager

1. Open your Node-RED Editor.
2. Go to the menu (☰) in the top right corner.
3. Select "Manage palette."
4. Go to the "Install" tab.
5. Search for node-red-contrib-msgraph.
6. Click on the install button next to the node-red-contrib-msgraph package.

Node Descriptions

msgraph-config

This node stores the necessary credentials to authenticate with the Microsoft Graph API and manages token caching.

Properties:

• clientId: The application (client) ID from your Azure AD app registration.
• clientSecret: The application secret from your Azure AD app registration.
• tenantId: The directory (tenant) ID of your Azure AD.
• redirectUri: The redirect URI configured in your Azure AD app registration.

msgraph-login

This node generates an authentication URL that redirects users to the Microsoft login page.

Usage: 1. Add the msgraph-login node to your flow. 2. Connect an inject node to trigger it. 3. Obtain the authentication URL from the output and visit it to log in to Microsoft Graph.

Example:

[
  {
    "id": "inject1",
    "type": "inject",
    "name": "Start Login",
    "props": [],
    "repeat": "",
    "crontab": "",
    "once": false,
    "onceDelay": "0.1",
    "wires": [["msgraph-login1"]]
  },
  {
    "id": "msgraph-login1",
    "type": "msgraph-login",
    "msGraphConfig": "msgraph-config1",
    "name": "",
    "wires": [["debug1"]]
  },
  {
    "id": "debug1",
    "type": "debug",
    "name": "Auth URL",
    "active": true,
    "tosidebar": true,
    "console": false,
    "tostatus": false
  }
]

msgraph-login-response

This node handles the OAuth2 callback, exchanges the authorization code for access tokens, and stores these tokens.

Usage: 1. Configure an HTTP input node to handle the redirect URI. It will be a GET request with your specified URI. 2. Connect it to the msgraph-login-response node.

Example:

[
  {
    "id": "http-in1",
    "type": "http in",
    "url": "/auth/callback",
    "method": "get",
    "name": "",
    "wires": [["msgraph-login-response1"]]
  },
  {
    "id": "msgraph-login-response1",
    "type": "msgraph-login-response",
    "msGraphConfig": "msgraph-config1",
    "name": "",
    "wires": [["debug2"]]
  },
  {
    "id": "debug2",
    "type": "debug",
    "name": "Login Response",
    "active": true,
    "tosidebar": true,
    "console": false,
    "tostatus": false
  }
]

msgraph-query

This node makes authenticated requests to the Microsoft Graph API using the access token.

Usage: 1. Add the msgraph-query node to your flow. 2. Configure the query parameters in msg.payload.

Example:

[
  {
    "id": "inject2",
    "type": "inject",
    "name": "Start Query",
    "props": [],
    "repeat": "",
    "crontab": "",
    "once": false,
    "onceDelay": "0.1",
    "wires": [["function2"]]
  },
  {
    "id": "function2",
    "type": "function",
    "name": "Set Query Params",
    "func": "msg.payload = {\n    endpoint: '/me', // Set the endpoint for the query\n    method: 'GET' // HTTP method\n};\nreturn msg;",
    "wires": [["msgraph-query1"]]
  },
  {
    "id": "msgraph-query1",
    "type": "msgraph-query",
    "msGraphConfig": "msgraph-config1",
    "name": "",
    "wires": [["debug3"]]
  },
  {
    "id": "debug3",
    "type": "debug",
    "name": "Query Result",
    "active": true,
    "tosidebar": true,
    "console": false,
    "tostatus": false
  }
]

Error Handling: This node provides detailed error messages with msg.payload and sets msg.statusCode to indicate HTTP status codes.

• 401: Unauthorized if access token is not available.
• 504: Gateway Timeout if no response is received.
• 500: Internal Server Error for other exceptions.

Development

Prerequisites

• Node.js
• Node-RED

Running Locally

1. Clone the repository.
2. Install dependencies.
3. Start Node-RED and test the nodes by creating flows.

git clone <repository-url>
cd node-red-contrib-msgraph
npm install
node-red

Contributing

1. Fork the repository.
2. Create a new branch.
3. Make your changes.
4. Submit a pull request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgements

• Node-RED
• Microsoft Authentication Library for JavaScript (MSAL.js)
• Icons8 for the icon on the nodes