Skip to content

Commit b1d1080

Browse files
jpmcbjpmcb
committed
feat: Azure AD MCP Oauth guide
Signed-off-by: John McBride <[email protected]>
1 parent 76861af commit b1d1080

File tree

2 files changed

+193
-0
lines changed

2 files changed

+193
-0
lines changed

‎docs/articles/configuring-azure-ad-for-mcp-auth.md‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
---
2+
title: Setting up Azure Active Directory as an Authentication Server for MCP OAuth Authentication
3+
---
4+
5+
In this guide, you'll learn how to configure Microsoft Entra ID (formerly Azure
6+
Active Directory) as an Authorization Server for use with the MCP Server
7+
handler. See the [MCP Server Handler docs](../handlers/mcp-server.md#oauth-authentication)
8+
for instructions on how to configure your Zuplo gateway to support OAuth
9+
authentication for your MCP Server.
10+
11+
This guide assumes that you already have a working Microsoft Azure account and
12+
an Entra ID tenant.
13+
14+
### Create an App Registration
15+
16+
First, you will need to create an App Registration in Microsoft Entra ID. This
17+
app registration will represent your MCP Server.
18+
19+
1. In the Azure portal, navigate to **Microsoft Entra ID** and click
20+
**App registrations**.
21+
2. Click **New registration**.
22+
3. Set the **Name** to something like "MCP Server" and set the
23+
**Supported account types** to the appropriate option for your use case
24+
(typically "Accounts in this organizational directory only").
25+
4. For **Redirect URI**, select "Web" and enter a placeholder URI like
26+
`https://example.com/callback` (this will be updated later during dynamic
27+
client registration).
28+
5. Click **Register**.
29+
6. Record the **Application (client) ID** from the overview page.
30+
31+
### Configure API Permissions and App ID URI
32+
33+
Next, you need to configure the app registration to act as an API with
34+
appropriate permissions.
35+
36+
1. In your app registration, click **Expose an API** in the left sidebar.
37+
2. Click **Set** next to **Application ID URI** and set it to the canonical UR
38+
of your MCP Server. For example, if your MCP Server is hosted at
39+
`https://my-gateway.zuplo.dev/mcp`, then the Application ID URI would
40+
be `https://my-gateway.zuplo.dev/mcp`. **The trailing slash is not required.**
41+
3. Click **Add a scope** and create a default scope:
42+
- **Scope name**: `access`
43+
- **Who can consent**: Admins and users
44+
- **Admin consent display name**: Access MCP Server
45+
- **Admin consent description**: Allows the application to access the MCP Server
46+
- **User consent display name**: Access MCP Server
47+
- **User consent description**: Allows the application to access the MCP Server
48+
- **State**: Enabled
49+
4. Click **Add scope**.
50+
51+
### Configure Authentication Settings
52+
53+
Configure the authentication settings for OAuth 2.0 support:
54+
55+
1. Click **Authentication** in the left sidebar.
56+
2. Under **Advanced settings**, ensure the following are configured:
57+
- **Allow public client flows**: Yes (to support PKCE)
58+
- **Supported account types**: Set appropriately for your use case
59+
3. Under **Implicit grant and hybrid flows**, you typically don't need to enable
60+
these for MCP OAuth flows.
61+
62+
### Create a Client Secret (Optional)
63+
64+
If your OAuth flow requires a client secret (though MCP typically uses PKCE),
65+
create one:
66+
67+
1. Click **Certificates & secrets** in the left sidebar.
68+
2. Click **New client secret**.
69+
3. Add a description and select an expiration period.
70+
4. Click **Add** and record the secret value immediately (it won't be shown again).
71+
72+
:::tip
73+
74+
If you configure an expiring secret, make sure to record the expiration date;
75+
you will need to renew the key before that day to avoid a service interruption.
76+
77+
:::
78+
79+
### Configure Token Configuration (Optional)
80+
81+
To customize the claims in your tokens:
82+
83+
1. Click **Token configuration** in the left sidebar.
84+
2. Add any optional or additional claims your MCP Server needs.
85+
3. For basic MCP functionality, the default claims are typically sufficient.
86+
87+
### Configure OAuth on Zuplo
88+
89+
To set up your gateway to support OAuth authentication for your MCP Server, you
90+
will need to do the following:
91+
92+
1. Create an OAuth policy on your MCP Server route. This policy will need to
93+
have the option `"oAuthResourceMetadataEnabled": true`, for example:
94+
95+
```json
96+
{
97+
"name": "mcp-oauth-inbound",
98+
"policyType": "open-id-jwt-auth-inbound",
99+
"handler": {
100+
"export": "OpenIdJwtInboundPolicy",
101+
"module": "$import(@zuplo/runtime)",
102+
"options": {
103+
"issuer": "https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0",
104+
"audience": "https://my-gateway.zuplo.dev/mcp",
105+
"oAuthResourceMetadataEnabled": true
106+
}
107+
}
108+
}
109+
```
110+
111+
Replace `YOUR_TENANT_ID` with your Microsoft Entra ID tenant ID, and set the audience to the Application ID URI you configured earlier.
112+
113+
2. Add the OAuth policy to the MCP Server route. For example:
114+
115+
```json
116+
"paths": {
117+
"/mcp": {
118+
"post": {
119+
"x-zuplo-route": {
120+
// etc. etc.
121+
// other properties and route handlers for MCP
122+
123+
"policies": {
124+
"inbound": [
125+
"mcp-oauth-inbound"
126+
]
127+
}
128+
}
129+
}
130+
}
131+
}
132+
```
133+
134+
3. Add the `OAuthProtectedResourcePlugin` to your `runtimeInit` function in the
135+
`zuplo.runtime.ts` file:
136+
137+
```ts
138+
import {
139+
RuntimeExtensions,
140+
OAuthProtectedResourcePlugin,
141+
} from "@zuplo/runtime";
142+
143+
export function runtimeInit(runtime: RuntimeExtensions) {
144+
runtime.addPlugin(
145+
new OAuthProtectedResourcePlugin({
146+
authorizationServers: ["https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0"],
147+
resourceName: "My MCP OAuth Resource",
148+
}),
149+
);
150+
}
151+
```
152+
153+
Replace `YOUR_TENANT_ID` with your Microsoft Entra ID tenant ID.
154+
155+
See the [OAuth Protected Resource Plugin docs](../programmable-api/oauth-protected-resource-plugin) for more details.
156+
157+
See the [MCP Server Handler docs](../handlers/mcp-server.md#oauth-authentication) for more details.
158+
159+
### Testing
160+
161+
Use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector),
162+
a developer focused tool for building MCP servers, to quickly and easily test
163+
out your MCP server:
164+
165+
```sh
166+
npx @modelcontextprotocol/inspector
167+
```
168+
169+
To connect to your remote Zuplo MCP server in the Inspector UI:
170+
171+
1. Set the **Transport Type** to "Streamable HTTP"
172+
2. Set the **URL** to your Zuplo gateway with the route used by the MCP Server
173+
Handler (i.e., `https://my-gateway.zuplo.dev/mcp`)
174+
3. You will need to login using the OAuth flow using the **Open Auth Settings** button.
175+
4. Hit **Connect**.
176+
177+
For debugging your OAuth configuration, hit the **Open Auth Settings** button
178+
in the Inspector UI to start the OAuth flow. When first setting up the OAuth
179+
flow, it is recommended to use the **Guided OAuth Flow** which you will see
180+
when you open the OAuth settings. This will allow you to debug the flow step by step.
181+
182+
You should be able to hit the **Continue** button in the Inspector UI at each
183+
step of the flow successfully. If you need more help debugging, see
184+
[Testing OAuth on Zuplo](../handlers/mcp-server.md#oauth-testing).
185+
186+
### Additional Resources
187+
188+
For more information about Azure AD OAuth configuration, see:
189+
190+
- [Setup Azure Active Directory SSO](./sso-azure-ad.md) - For general Azure AD setup guidance
191+
- [OAuth Authentication](./oauth-authentication.md) - For general OAuth concepts in Zuplo
192+
- [Microsoft Entra ID documentation](https://learn.microsoft.com/en-us/entra/identity-platform/) - Official Microsoft documentation

‎sidebar.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -211,6 +211,7 @@ export const docs: Navigation = [
211211
"articles/use-openapi-extension-data",
212212
"articles/non-standard-ports",
213213
"articles/convert-urls-to-openapi",
214+
"articles/configuring-azure-ad-for-mcp-auth",
214215
],
215216
},
216217
{

0 commit comments

Comments
 (0)