Set up Microsoft Entra ID

Configure Microsoft Entra ID (Azure AD) as an OAuth identity provider for MCP authentication with agentgateway.

Secure your Model Context Protocol (MCP) servers with OAuth 2.0 authentication by using agentgateway and Microsoft Entra ID (formerly Azure Active Directory) as the identity provider.

About this guide

In this guide, you configure the agentgateway proxy to protect a static MCP server with MCP auth by using Microsoft Entra ID as the authorization server. Because Entra does not fully implement the OAuth behaviors that the MCP authorization specification assumes, agentgateway includes a native Entra provider that bridges the gaps. When you set provider: Entra, agentgateway serves RFC 8414 authorization server metadata from Entra’s OIDC discovery document, strips the RFC 8707 resource parameter that Entra rejects, and short-circuits Dynamic Client Registration with your pre-registered application (client) ID.

This guide configures Entra app registrations that are public clients using PKCE, such as local MCP clients. Confidential clients (app registrations under the Entra Web platform) require a client secret at the token endpoint. On Kubernetes, injecting that secret through the recommended jwtAuthentication.mcp traffic policy is not yet supported. If you need confidential-client support today, use agentgateway in standalone mode, which accepts a clientSecret field on the MCP authentication policy.

For more information about MCP auth, see the About MCP auth page.

Before you begin

Set up an agentgateway proxy.
Follow the steps to set up an MCP server with a fetch tool.

Install the experimental channel Gateway API.

kubectl apply --server-side -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.6.0/experimental-install.yaml

Register an application in Microsoft Entra ID and collect the values that agentgateway needs.
1. Make sure that you have access to a Microsoft Entra ID tenant. If you do not have one, you can create a free tenant for development purposes.
2. Register an application in the Microsoft Entra admin center. For Supported account types, choose the option that fits your organization. Under Redirect URI, select the Mobile and desktop applications platform and add the callback URLs of the MCP clients that you plan to connect.
3. From the app’s Overview page, note the Directory (tenant) ID and the Application (client) ID, and save them as environment variables.
  export ENTRA_TENANT_ID=<your-tenant-id> export ENTRA_CLIENT_ID=<your-application-client-id>
4. Select Expose an API. Next to Application ID URI, click Set and accept the default value of api://${ENTRA_CLIENT_ID}. Then click Add a scope, enter a scope name such as mcp_access, set Who can consent to Admins and users, and click Add scope.

Create the JWKS backend

Create a AgentgatewayBackend that points to the Microsoft login endpoint, and a BackendTLSPolicy that originates a TLS connection to it. The JWT authentication policy uses this backend to fetch Entra’s public keys for token signature validation.

Create an AgentgatewayBackend for the Microsoft login endpoint.

kubectl apply -f- <<EOF
apiVersion: agentgateway.dev/v1alpha1
kind: AgentgatewayBackend
metadata:
  name: entra-jwks
spec:
  static:
    host: login.microsoftonline.com
    port: 443
EOF

Create a BackendTLSPolicy that originates a TLS connection to the entra-jwks backend by using well-known trusted CA certificates.

kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: BackendTLSPolicy
metadata:
  name: entra-jwks
spec:
  targetRefs:
    - name: entra-jwks
      kind: AgentgatewayBackend
      group: agentgateway.dev
  validation:
    hostname: login.microsoftonline.com
    wellKnownCACertificates: System
EOF

Configure MCP auth

With your MCP backend configured, create an AgentgatewayPolicy that enforces Entra authentication for the MCP backend.

Create an AgentgatewayPolicy with MCP authentication configuration. MCP authentication is configured at the route level by using traffic.jwtAuthentication with the mcp extension field. The route-level placement aligns MCP auth with standard JWT authentication and lets you use JWT claims in other route-level policies, such as authorization, rate limiting, and transformations.

kubectl apply -f - <<EOF
apiVersion: agentgateway.dev/v1alpha1
kind: AgentgatewayPolicy
metadata:
  name: mcp-entra-authn
spec:
  # Target the HTTPRoute to apply authentication at the route level
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: mcp
  traffic:
    jwtAuthentication:
      mode: Strict
      providers:
        # v2 issuer form. The v1 form https://sts.windows.net/<tenant-id>/ is
        # also supported; use it when the app registration mints v1 tokens.
      - issuer: "https://login.microsoftonline.com/${ENTRA_TENANT_ID}/v2.0"
        # List both the api://<client-id> and bare <client-id> audience
        # formats to accept the aud claim that Entra mints for v1 and v2 tokens.
        audiences:
        - "api://${ENTRA_CLIENT_ID}"
        - "${ENTRA_CLIENT_ID}"
        jwks:
          remote:
            backendRef:
              name: entra-jwks
              kind: AgentgatewayBackend
              group: agentgateway.dev
              port: 443
            jwksPath: "/${ENTRA_TENANT_ID}/discovery/v2.0/keys"
      mcp:
        # Use the native Entra provider to bridge Entra's OAuth behaviors
        provider: Entra
        # Entra has no Dynamic Client Registration, so the gateway answers
        # registration requests with this pre-registered client ID.
        clientId: "${ENTRA_CLIENT_ID}"
        resourceMetadata:
          resource: http://localhost:8080/mcp
          scopesSupported:
          - "api://${ENTRA_CLIENT_ID}/mcp_access"
          bearerMethodsSupported:
          - header
EOF

Review the following table to understand this configuration. For more information about the traffic.jwtAuthentication field, see the API docs.

Setting	Description
`providers[].issuer`	The Entra token issuer URL. Use the v2 form `https://login.microsoftonline.com/<tenant-id>/v2.0` or the v1 form `https://sts.windows.net/<tenant-id>/`, depending on which version your app registration mints. This value must match the `iss` claim in the token.
`providers[].audiences`	The accepted audiences. List both `api://<client-id>` and the bare `<client-id>` to accept the `aud` claim formats that Entra mints for v1 and v2 tokens.
`providers[].jwks.remote.backendRef`	The `entra-jwks` backend that points to `login.microsoftonline.com`.
`providers[].jwks.remote.jwksPath`	The path to Entra’s JWKS endpoint for your tenant.
`mcp.provider`	The identity provider. Set to `Entra` to enable the native Entra bridging behavior.
`mcp.clientId`	The Application (client) ID of your Entra app registration. Because Entra has no Dynamic Client Registration, agentgateway answers registration requests with this value.
`mcp.resourceMetadata`	MCP OAuth resource metadata for discovery. Includes the resource identifier, supported scopes, and bearer token methods.

Verify that the policy was accepted.

kubectl get AgentgatewayPolicy mcp-entra-authn -o yaml

Update the HTTPRoute that routes incoming traffic to the MCP server to include the discovery paths for the MCP resource and authorization server. This way, the agentgateway proxy can retrieve the resource and authorization server metadata during the MCP auth flow. The authorization server path uses a prefix match so that the proxy can serve the bridged Entra metadata and proxy the authorize and token endpoints under it.

kubectl apply -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: mcp
spec:
  parentRefs:
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: agentgateway-proxy
    namespace: agentgateway-system
  rules:
  - filters:
      - type: CORS
        cors:
          allowCredentials: true
          allowHeaders:
            - Origin
            - Authorization
            - Content-Type
          allowMethods:
            - "*"
          allowOrigins:
            - "*"
          exposeHeaders:
            - Origin
            - X-HTTPRoute-Header
          maxAge: 86400
    backendRefs:
    - group: agentgateway.dev
      kind: AgentgatewayBackend
      name: mcp-backend
    matches:
    # Main MCP endpoint to connect to the MCP server
    - path:
        type: PathPrefix
        value: /mcp
    # Path to access resource server metadata
    - path:
        type: PathPrefix
        value: /.well-known/oauth-protected-resource/mcp
    # Path to access the bridged authorization server metadata and proxied endpoints
    - path:
        type: PathPrefix
        value: /.well-known/oauth-authorization-server/mcp
EOF

Verify MCP auth

Verify the auth flow with the MCP inspector. Because the flow redirects you to Microsoft to sign in, this verification is interactive and requires a live Entra tenant.

Open the MCP inspector.

npx @modelcontextprotocol/inspector@0.21.2

From the MCP Inspector menu, connect to your agentgateway address:
- Transport Type: Select Streamable HTTP.
- URL: Enter the agentgateway address and the /mcp path. For a LoadBalancer, use http://${INGRESS_GW_ADDRESS}/mcp. For a port-forwarded proxy, use http://localhost:8080/mcp.
- Click Connect. Verify that the connection fails because authentication is required.
Click Open Auth Settings and run through the OAuth flow. During the flow, the MCP inspector discovers the bridged authorization server metadata, registers with your pre-configured clientId, and redirects you to Microsoft to sign in. After you sign in and the token is issued, agentgateway validates the Entra token and completes the connection.
Verify that tool calls work without re-authentication. From the Tools tab, click List Tools, select the fetch tool, enter a URL such as https://example.com/, and click Run Tool. The call succeeds because the token from the initial connection is reused for all tool calls within the session.

Clean up

You can remove the resources that you created in this guide.

kubectl delete AgentgatewayPolicy mcp-entra-authn
kubectl delete backendtlspolicy entra-jwks
kubectl delete AgentgatewayBackend entra-jwks
kubectl delete httproute mcp

Set up MCP auth

Was this page helpful?