Skip to content

Commit d1d9364

Browse files
anshulkhantwalanshulkhantwal
committed
Enabling optional Azure MI based AUTH
1 parent 43e6f98 commit d1d9364

File tree

9 files changed

+2507
-3801
lines changed

9 files changed

+2507
-3801
lines changed

‎README.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ A Model Context Protocol server for interacting with MongoDB Databases and Mongo
1212
- [Prerequisites](#prerequisites)
1313
- [Setup](#setup)
1414
- [Quick Start](#quick-start)
15+
- [HTTP Transport Authentication](#http-authentication)
1516
- [🛠️ Supported Tools](#supported-tools)
1617
- [MongoDB Atlas Tools](#mongodb-atlas-tools)
1718
- [MongoDB Database Tools](#mongodb-database-tools)
@@ -277,6 +278,103 @@ npx -y mongodb-mcp-server@latest --transport http --httpHost=0.0.0.0 --httpPort=
277278

278279
> **Note:** The default transport is `stdio`, which is suitable for integration with most MCP clients. Use `http` transport if you need to interact with the server over HTTP.
279280
281+
### HTTP Authentication Middleware
282+
283+
<a name="http-authentication"></a>
284+
285+
The HTTP transport supports pluggable authentication strategies selected via the `httpAuthMode` configuration option.
286+
287+
Current modes:
288+
289+
- `none` (default) – No authentication. Every request is accepted. Only use this in local / trusted network environments. Do **NOT** expose an unauthenticated instance to the public internet.
290+
- `azure-managed-identity` – Validates Azure Entra ID (Managed Identity / Service Principal) issued **access tokens** presented via `Authorization: Bearer <token>`.
291+
292+
This setting is ONLY evaluated when `transport` is `http`; it is ignored for the default `stdio` transport.
293+
294+
#### Azure Managed Identity / Entra ID Options
295+
296+
Environment variables map 1:1 to the camelCase keys with the `MDB_MCP_` prefix:
297+
298+
| Key | Env Var | Required | Description |
299+
| --- | ------- | -------- | ----------- |
300+
| `httpAuthMode` | `MDB_MCP_HTTP_AUTH_MODE` | No (defaults to `none`) | Set to `azure-managed-identity` to enable Azure token validation. |
301+
| `azureManagedIdentityTenantId` | `MDB_MCP_AZURE_MANAGED_IDENTITY_TENANT_ID` | Yes (when `httpAuthMode=azure-managed-identity`) | Azure Entra tenant ID used to resolve OpenID configuration and signing keys. |
302+
| `azureManagedIdentityClientId` | `MDB_MCP_AZURE_MANAGED_IDENTITY_CLIENT_ID` | No | Fallback expected audience (token `aud`) if `azureManagedIdentityAudience` is not supplied. Typically your application (service principal) client ID. |
303+
| `azureManagedIdentityAudience` | `MDB_MCP_AZURE_MANAGED_IDENTITY_AUDIENCE` | No | Explicit audience override. If set, token `aud` must match this value (takes precedence over clientId). |
304+
| `azureManagedIdentityAllowedAppIds` | `MDB_MCP_AZURE_MANAGED_IDENTITY_ALLOWED_APP_IDS` | No | Comma-separated allow‑list of `appid`/`azp` claim values. If provided, token must match one. |
305+
| `azureManagedIdentityRequiredRoles` | `MDB_MCP_AZURE_MANAGED_IDENTITY_REQUIRED_ROLES` | No | Comma-separated list of application roles (in the `roles` claim) that must be present. |
306+
| `azureManagedIdentityRoleMatchMode` | `MDB_MCP_AZURE_MANAGED_IDENTITY_ROLE_MATCH_MODE` | No (defaults to `all`) | Whether **all** or **any** of the required roles must be present. |
307+
308+
#### Quick Start: No Auth (default)
309+
310+
```bash
311+
npx -y mongodb-mcp-server@latest --transport http
312+
# httpAuthMode defaults to 'none'
313+
```
314+
315+
#### Quick Start: Azure Managed Identity Auth
316+
317+
Using environment variables (recommended):
318+
319+
```bash
320+
export MDB_MCP_HTTP_AUTH_MODE=azure-managed-identity
321+
export MDB_MCP_AZURE_MANAGED_IDENTITY_TENANT_ID="<tenant-id>"
322+
# Optional audience controls
323+
# export MDB_MCP_AZURE_MANAGED_IDENTITY_CLIENT_ID="<app-client-id>"
324+
# OR explicit audience override:
325+
# export MDB_MCP_AZURE_MANAGED_IDENTITY_AUDIENCE="api://your-app-resource-id"
326+
327+
# Optional constraints
328+
# export MDB_MCP_AZURE_MANAGED_IDENTITY_ALLOWED_APP_IDS="<appId1>,<appId2>"
329+
# export MDB_MCP_AZURE_MANAGED_IDENTITY_REQUIRED_ROLES="Reader,Query"
330+
# export MDB_MCP_AZURE_MANAGED_IDENTITY_ROLE_MATCH_MODE=any
331+
332+
npx -y mongodb-mcp-server@latest --transport http
333+
```
334+
335+
Using CLI flags (non-secret values only):
336+
337+
```bash
338+
npx -y mongodb-mcp-server@latest \
339+
--transport http \
340+
--httpAuthMode azure-managed-identity \
341+
--azureManagedIdentityTenantId <tenant-id>
342+
```
343+
344+
#### Obtaining an Access Token (Example)
345+
346+
Acquire a token for your application (service principal or managed identity) using the Azure CLI; then send it on each request:
347+
348+
```bash
349+
# Interactive login or ensure your automation identity is already authenticated
350+
az login --tenant <tenant-id>
351+
352+
# If using an application (service principal) audience
353+
TOKEN=$(az account get-access-token --tenant <tenant-id> --resource <audience-or-clientId> --query accessToken -o tsv)
354+
355+
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:3000/
356+
```
357+
358+
> The actual HTTP path structure follows the MCP Streamable HTTP transport spec. For simple readiness checks you can hit the root path; authenticated RPC calls must include the Bearer token header.
359+
360+
#### Role & App ID Enforcement
361+
362+
- If `azureManagedIdentityAllowedAppIds` is set, the token must contain an `appid` (or `azp`) claim matching one of the values.
363+
- If `azureManagedIdentityRequiredRoles` is set, the token `roles` claim must contain roles based on `azureManagedIdentityRoleMatchMode` (`all` vs `any`).
364+
365+
#### Adding New Auth Modes
366+
367+
You can introduce additional HTTP auth strategies (e.g. API keys, other OIDC providers) by:
368+
369+
1. Creating a new provider/middleware under `src/transports/auth/` implementing the required interface.
370+
2. Extending the factory (`createAuthMiddleware`) to map a new `httpAuthMode` string to your middleware.
371+
3. Adding any new configuration keys (environment variables should follow the `MDB_MCP_` + SNAKE_CASE pattern).
372+
4. Documenting the new mode (update this section & configuration table) and adding tests.
373+
374+
This design keeps the core transport decoupled from auth specifics.
375+
376+
Authentication for the HTTP transport is selected via the `httpAuthMode` configuration option. The server uses a factory function (`createAuthMiddleware` in `src/transports/auth/authMiddlewareFactory.ts`) to resolve and attach the proper Express middleware. All auth strategies live under `src/transports/auth/` which keeps the transport implementation decoupled from individual authentication strategies so new modes can be added with minimal changes.
377+
280378
## 🛠️ Supported Tools
281379

282380
### Tool List
@@ -355,6 +453,13 @@ The MongoDB MCP Server can be configured using multiple methods, with the follow
355453
| `transport` | `MDB_MCP_TRANSPORT` | stdio | Either 'stdio' or 'http'. |
356454
| `httpPort` | `MDB_MCP_HTTP_PORT` | 3000 | Port number. |
357455
| `httpHost` | `MDB_MCP_HTTP_HOST` | 127.0.0.1 | Host to bind the http server. |
456+
| `httpAuthMode` | `MDB_MCP_HTTP_AUTH_MODE` | none | HTTP auth strategy when `transport=http`. Supported: `none`, `azure-managed-identity`. Ignored for `stdio` transport. |
457+
| `azureManagedIdentityTenantId` | `MDB_MCP_AZURE_MANAGED_IDENTITY_TENANT_ID` | <not set> | Required when `httpAuthMode=azure-managed-identity`. Azure Entra tenant used to fetch OpenID configuration & signing keys. |
458+
| `azureManagedIdentityClientId` | `MDB_MCP_AZURE_MANAGED_IDENTITY_CLIENT_ID` | <not set> | Optional expected audience/client id if `azureManagedIdentityAudience` not provided. |
459+
| `azureManagedIdentityAudience` | `MDB_MCP_AZURE_MANAGED_IDENTITY_AUDIENCE` | <not set> | Optional explicit audience override for access token `aud` claim (takes precedence over client id fallback). |
460+
| `azureManagedIdentityAllowedAppIds` | `MDB_MCP_AZURE_MANAGED_IDENTITY_ALLOWED_APP_IDS` | <not set> | Optional comma-separated allow-list of `appid` / `azp` claim values; if set the token must match one. |
461+
| `azureManagedIdentityRequiredRoles` | `MDB_MCP_AZURE_MANAGED_IDENTITY_REQUIRED_ROLES` | <not set> | Optional comma-separated list of application roles the token must include (in `roles` claim). |
462+
| `azureManagedIdentityRoleMatchMode` | `MDB_MCP_AZURE_MANAGED_IDENTITY_ROLE_MATCH_MODE` | all | Whether `all` or `any` of the listed required roles must be present. |
358463
| `idleTimeoutMs` | `MDB_MCP_IDLE_TIMEOUT_MS` | 600000 | Idle timeout for a client to disconnect (only applies to http transport). |
359464
| `maxBytesPerQuery` | `MDB_MCP_MAX_BYTES_PER_QUERY` | 16777216 (16MiB) | The maximum size in bytes for results from a `find` or `aggregate` tool call. This serves as an upper bound for the `responseBytesLimit` parameter in those tools. |
360465
| `maxDocumentsPerQuery` | `MDB_MCP_MAX_DOCUMENTS_PER_QUERY` | 100 | The maximum number of documents that can be returned by a `find` or `aggregate` tool call. For the `find` tool, the effective limit will be the smaller of this value and the tool's `limit` parameter. |

0 commit comments

Comments
 (0)