Merge pull request #307750 from mattchenderson/ea-mcp

App Service Auth for MCP

Author: JamesJBarnett

articles/app-service/configure-authentication-mcp.md

@@ -0,0 +1,60 @@
+---
+title: Configure MCP server authorization
+description: Learn how to configure Model Context Protocol (MCP) server authorization in Azure App Service and Azure Functions
+ms.topic: how-to
+ms.date: 11/04/2025
+author: mattchenderson
+ms.author: mahender
+ms.service: azure-app-service
+---
+
+# Configure built-in MCP server authorization (Preview)
+
+[App Service Authentication](./overview-authentication-authorization.md) allows you to control access to your Model Context Protocol (MCP) server by requiring MCP clients to authenticate with an identity provider. You can make your app comply with the [MCP server authorization specification][spec] by following the instructions in this article.
+
+> [!IMPORTANT]
+> MCP server authorization defines access to the server, and it doesn't provide granular control to individual MCP tools or other constructs.
+
+## Configure an identity provider
+
+[Configure App Service Authentication with an identity provider](./overview-authentication-authorization.md#identity-providers). The identity provider registration should be unique for the MCP server. Don't reuse an existing registration from another application component.
+
+As you create the registration, make note of what scopes are defined in your registration or in the identity provider's documentation.
+
+## Configure protected resource metadata (preview)
+
+MCP server authorization requires that the server host [protected resource metadata (PRM)](./overview-authentication-authorization.md#protected-resource-metadata-preview). Support for PRM with App Service Authentication is currently in preview.
+
+To configure PRM for your MCP server, set the `WEBSITE_AUTH_PRM_DEFAULT_WITH_SCOPES` application setting to a comma-separated list of scopes for your application. The scopes you need are either defined as part of your app registration or documented by your identity provider. For example, if you used the [Microsoft Entra ID provider](./configure-authentication-provider-aad.md) and let App Service create the registration for you, a default scope of `api://<client-id>/user_impersonation` was created. You would set `WEBSITE_AUTH_PRM_DEFAULT_WITH_SCOPES` to that value.
+
+## MCP client considerations
+
+In order to sign in users, the MCP client must be registered with the identity provider. Some providers support Dynamic Client Registration (DCR), but many don't, including Microsoft Entra ID. When DCR isn't available, the client needs to be preconfigured with a client ID. Consult the documentation for your client or client SDK to understand how to provide a client ID.
+
+### Entra ID consent authoring
+
+If you're using Microsoft Entra ID, you can specify known client applications and mark them as preauthorized for access. preauthorization is recommended when possible. Without preauthorization, users or an administrator need to [consent to the MCP server registration](/entra/identity-platform/permissions-consent-overview#consent) and any permissions it requires.
+
+For user consent scenarios, consent authoring involves the MCP client using interactive login to display the consent prompt. Some MCP clients might not surface an interactive login. For example, if you are building an MCP tool to be used by GitHub Copilot in Visual Studio Code, the client attempts to use the context of the logged-in user and doesn't display a consent prompt. In these cases, preauthorizing the client application is required to avoid consent issues.
+
+For dev/test purposes, you can author user consent for yourself by signing into the application directly in a browser. Navigating to `<your-app-url>/.auth/login/aad` initiates the sign-in flow and prompts you for consent if needed. Then you can attempt sign-in from another client.
+
+## MCP server considerations
+
+App Service Authentication validates tokens provided by MCP clients and applies any configured authorization policies before responding to the MCP initialization request. You might need to update your authorization rules for the MCP scenario. For example, if you used the Microsoft Entra ID provider and let App Service create the registration for you, a default policy only allows tokens obtained by the app itself. You therefore would add your MCP client to the allowed applications list in the auth configuration. For more information, see [Use a built-in authorization policy](./configure-authentication-provider-aad.md#use-a-built-in-authorization-policy).
+
+MCP server frameworks frequently abstract away the transport, but in some cases they might expose the underlying HTTP context. When the HTTP context is available, you can [access user claims and other authentication information](./configure-authentication-user-identities.md) provided by App Service Authentication.
+
+> [!CAUTION]
+> The token used for MCP server authorization is meant to represent access to your MCP server, and not to a downstream resource. Pass-through scenarios where the server forwards its token create security vulnerabilities, so avoid these patterns. If you need to access a downstream resource, obtain a new token through the on-behalf-of flow or another mechanism for explicit delegation.
+
+## Related content
+
+- [Model Context Protocol Authorization specification][spec]
+- [Azure Functions Model Context Protocol bindings](../azure-functions/functions-bindings-mcp.md)
+- [Integrate an App Service app as an MCP Server (.NET)](./tutorial-ai-model-context-protocol-server-dotnet.md)
+- [Integrate an App Service app as an MCP Server (Java)](./tutorial-ai-model-context-protocol-server-java.md)
+- [Integrate an App Service app as an MCP Server (Node.js)](./tutorial-ai-model-context-protocol-server-node.md)
+- [Integrate an App Service app as an MCP Server (Python)](./tutorial-ai-model-context-protocol-server-python.md)
+
+[spec]: https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization

articles/app-service/overview-authentication-authorization.md

@@ -170,6 +170,27 @@ App Service authentication mitigates cross-site request forgery by inspecting cl
 
 When a request fulfills all these conditions, App Service authentication automatically rejects it. You can work around this mitigation logic by adding your external domain to the redirect list in **Settings** > **Authentication** > **Edit authentication settings** > **Allowed external redirect URLs**.
 
+### Protected resource metadata (preview)
+
+App Service can serve OAuth 2.0 protected resource metadata, as defined in [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728). This can help OAuth 2.0 clients understand how to interact with your app. It is required for [Model Context Protocol (MCP) server authorization](./configure-authentication-mcp.md).
+
+> [!NOTE]
+> Support for protected resource metadata is currently in preview, and the way you configure it may change before the feature is generally available.
+
+During the preview period, you can enable a default protected resource metadata document by configuring the `WEBSITE_AUTH_PRM_DEFAULT_WITH_SCOPES` [application setting](./configure-common.md#configure-app-settings) with a comma-separated list of scopes needed by the application. For example, when you let App Service configure the Microsoft Entra provider for you, it will set up a scope like `api://<client-id>/user_impersonation`, replacing `<client-id>` with the actual client ID of your app registration.
+
+The default protected resource metadata document includes the following properties:
+
+| Property | Description |
+|-|-|
+| `resource` | The resource URI corresponding to the endpoint at which the protected resource metadata was accessed. |
+| `authorization_servers` | A list of authorization servers for the identity providers that you have configured. |
+| `scopes_supported` | The list of scopes that you specified in the `WEBSITE_AUTH_PRM_DEFAULT_WITH_SCOPES` application setting. |
+
+Additional properties are not supported when using the default configuration.
+
+Configuring the default protected resource metadata document also changes how App Service handles unauthenticated requests for APIs. When the app issues an authorization challenge, it includes the URL of the protected resource metadata, which the client can then retrieve and process. The challenge also includes the scopes that you configured in the `WEBSITE_AUTH_PRM_DEFAULT_WITH_SCOPES` application setting.
+
 ## Considerations for using Azure Front Door
 
 When you're using Azure App Service with authentication behind Azure Front Door or other reverse proxies, consider the following actions.

articles/app-service/reference-app-settings.md

@@ -535,6 +535,7 @@ The following environment variables are related to [App Service authentication](
 | `WEBSITE_AUTH_ENABLED` | Read-only. Injected into a Windows or Linux app to indicate whether App Service authentication is enabled. |
 | `WEBSITE_AUTH_ENCRYPTION_KEY` | By default, the automatically generated key is used as the encryption key. To override, set to a desired key. We recommend this environment variable if you want to share tokens or sessions across multiple apps. If you specify it, it supersedes the `MACHINEKEY_DecryptionKey` setting. |
 | `WEBSITE_AUTH_SIGNING_KEY` | By default, the automatically generated key is used as the signing key. To override, set to a desired key. We recommend this environment variable if you want to share tokens or sessions across multiple apps. If you specify it, it supersedes the `MACHINEKEY_ValidationKey` setting. |
+| `WEBSITE_AUTH_PRM_DEFAULT_WITH_SCOPES` | A comma-separated list of scopes needed by the application. When set, this variable configures a default protected resource metadata document, which declares that the specified scopes are supported. The scopes are also included in authentication challenges returned by the application. |
 
 <!-- System settings
 WEBSITE_AUTH_RUNTIME_VERSION

articles/app-service/toc.yml

@@ -416,6 +416,8 @@ items:
       href: configure-authentication-api-version.md
     - name: Use file-based configuration
       href: configure-authentication-file-based.md
+    - name: MCP server authorization
+      href: configure-authentication-mcp.md
 - name: Security and networking
   items:
     - name: Security overview

articles/azure-functions/TOC.yml

@@ -521,6 +521,8 @@
       href: ../app-service/configure-authentication-api-version.md?toc=/azure/azure-functions/toc.json
     - name: File-based configuration
       href: ../app-service/configure-authentication-file-based.md?toc=/azure/azure-functions/toc.json
+    - name: MCP server authorization
+      href: ../app-service/configure-authentication-mcp.md?toc=/azure/azure-functions/toc.json
   - name: Secure
     items:
     - name: Work with access keys

articles/azure-functions/functions-bindings-mcp.md

@@ -153,7 +153,7 @@ MCP clients accept this configuration in various ways. Consult the documentation
 
 ## Related articles
 
-[Create a tool endpoint in your remote MCP server](./functions-bindings-mcp-trigger.md) 
+- [Create a tool endpoint in your remote MCP server](./functions-bindings-mcp-trigger.md) 
+- [Configure built-in MCP server authorization][authorization]
 
-
-[extension bundle]: ./extension-bundles.md
+[authorization]: ../app-service/configure-authentication-mcp.md?toc=/azure/azure-functions/toc.json