npm package: @proxsys/n8n-nodes-multitenantmicrosoft
Description: A multitenant node for accessing multiple Microsoft tenants in the same n8n workflow using the same credential-type.
Author: Proxsys
Latest version: 0.2.3

# @proxsys/n8n-nodes-multitenantmicrosoft

An n8n community node that enables authenticated HTTP requests to Microsoft APIs (e.g. Microsoft Graph) across **multiple Azure AD tenants within a single workflow** — without needing separate credentials per tenant.

- [Why this node exists](#why-this-node-exists)
- [How it works](#how-it-works)
- [Installation](#installation)
- [Quick start](#quick-start)
- [Credentials](#credentials)
- [Operations](#operations)
- [Security](#security)
- [Troubleshooting](#troubleshooting)
- [Compatibility](#compatibility)
- [Resources](#resources)
- [License](#license)

---

## Why this node exists

Standard n8n Microsoft credentials are tied to a single tenant — one credential, one tenant. When you need to query or act on data from multiple Azure AD tenants in one flow (e.g. an MSP managing dozens of customer environments), the standard approach requires creating and maintaining a separate credential for each tenant.

This node solves that by decoupling the **signing identity** (your app registration + certificate, configured once in the credential) from the **target tenant** (supplied per node execution via `tenantId` and `clientId` parameters). The credential fetches and caches a fresh access token scoped to whichever tenant is requested, refreshing it automatically when it expires or when the tenant changes.

## Installation

### Via the n8n web UI (recommended)

1. Open your n8n instance in the browser.
2. Go to **Settings** > **Community Nodes**.
3. Click **Install a community node**.
4. Enter the package name: `@proxsys/n8n-nodes-multitenantmicrosoft`
5. Click **Install**.

---

## Quick start

This example shows how to iterate over a list of tenants and fetch users from Microsoft Graph for each one.

1. **Create a credential** — go to Credentials > New > **Multi-Tenant Microsoft Client Assertion Credential API**. Choose **KeyVault with App Access** as signing method and fill in the Key Vault details.

2. **Add a data source** — use a data table, database query, or any node that outputs items with `tenant_id` and `client_id` columns.

3. **Add the Multi-Tenant node** — connect it to the data source and configure:
   - **Tenant ID**: `{{ $json.tenant_id }}` (expression)
   - **Client ID**: `{{ $json.client_id }}` (expression)
   - **Method**: `GET`
   - **URL**: `https://graph.microsoft.com/v1.0/users`

4. **Run the workflow** — the node will automatically fetch a new access token for each tenant and return the results per item.

---

## Credentials

**Credential type:** `Multi-Tenant Microsoft Client Assertion Credential API`

The credential holds the signing configuration used to generate client assertions. The target tenant is **not** configured here — it is passed in at the node level per execution item.

### Signing methods

| Method                             | When to use                                                                                                     |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **KeyVault with Managed Identity** | n8n runs on Azure with a Managed Identity assigned; Key Vault access is granted to that identity                |
| **KeyVault with App Access**       | Key Vault access via a dedicated App Registration (Client ID + Secret). Ask the Automation Team for the values. |
| **Self-sign with Certificate**     | Local development only. Provide a PEM certificate and private key directly in the credential.                   |

> **Important:** The credential name must match the workflow name. This is a security measure that prevents credentials from being shared across workflows.

---

## Operations

The node acts as a multi-tenant-aware HTTP Request node. Configure it like a standard HTTP Request node, with two additional required fields:

| Field       | Description                                 | Example                                |
| ----------- | ------------------------------------------- | -------------------------------------- |
| `Tenant ID` | Azure AD tenant GUID for the target tenant  | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
| `Client ID` | App Registration (client) ID in that tenant | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |

Both `Tenant ID` and `Client ID` accept expressions, so you can feed them dynamically from a data table or previous node output (e.g. `{{ $json.tenant_id }}`).

The node also supports:

- **Query parameters** — e.g. `$select`, `$filter`, `$top` for Microsoft Graph
- **Custom headers** — e.g. `ConsistencyLevel: eventual`
- **Request body** — JSON, Form-Data, Form-Urlencoded, Raw, or n8n Binary File
- **Pagination** — same options as the standard HTTP node, works with `@odata.nextLink`
- **SSL options** and **timeout** configuration

The `Authorization: Bearer <token>` header is injected automatically.

---

## Security

- **Client assertion auth** — no long-lived client secrets are used. Client assertions are short-lived JWTs (5-minute expiry) signed by the Key Vault. The private key never leaves the vault.
- **Workflow–credential name binding** — the credential name must match the workflow name. This prevents a credential from being accidentally reused across unrelated workflows.
- **Token–tenant validation** — every request validates that the cached token's `tid` claim matches the requested tenant. A mismatch triggers an automatic refresh.
- **Non-reversible certificate naming** — the Key Vault certificate name is calulated using a special algorithm to prevent reversible naming.

---

## Troubleshooting

| Symptom                                         | Likely cause                            | What to do                                                                      |
| ----------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------- |
| `Invalid client secret provided`                | Wrong Key Vault secret                  | Use the secret **Value** from Azure, not the Secret ID                          |
| `Application with identifier ... was not found` | Wrong Client ID or Tenant ID            | Verify the IDs — check if Key Vault IDs vs customer IDs are in the right fields |
| `The connection cannot be established`          | Wrong Key Vault URL                     | Verify the Key Vault URL in the credential                                      |
| `CertificateNotFound`                           | No certificate uploaded for this tenant | Upload the certificate                                                          |
| `Forbidden - Insufficient privileges`           | App registration lacks API permissions  | Grant the right permissions                                                     |

---

## Compatibility

| Dependency   | Version                    |
| ------------ | -------------------------- |
| n8n          | Tested with `2.12.3`       |
| n8n-workflow | `^1.0.0` (peer dependency) |

Requires an n8n instance with credential `preAuthentication` support.

---

## Resources

- [n8n community nodes documentation](https://docs.n8n.io/integrations/#community-nodes)
- [Microsoft identity platform — certificate credentials](https://learn.microsoft.com/en-us/entra/identity-platform/certificate-credentials)
- [Microsoft Graph API](https://learn.microsoft.com/en-us/graph/overview)
- [Azure Key Vault documentation](https://learn.microsoft.com/en-us/azure/key-vault/)