node-red-contrib-msgraph
v1.2.0
Published
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.
Downloads
123
Maintainers
Readme
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.
Changelog
1.2.0 Added a logout node; Require user to consent to updated permissions on subsequent log in.
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
- Open your Node-RED Editor.
- Go to the menu (☰) in the top right corner.
- Select "Manage palette."
- Go to the "Install" tab.
- Search for
node-red-contrib-msgraph
. - 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:
- Add the
msgraph-login
node to your flow. - Connect an inject node to trigger it.
- 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:
- Configure an HTTP input node to handle the redirect URI. It will be a GET request with your specified URI.
- 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:
- Add the
msgraph-query
node to your flow. - 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
- Clone the repository.
- Install dependencies.
- Start Node-RED and test the nodes by creating flows.
git clone <repository-url>
cd node-red-contrib-msgraph
npm install
node-red
Contributing
- Fork the repository.
- Create a new branch.
- Make your changes.
- Submit a pull request.
License
This project is licensed under the MIT License - see the LICENSE file for details.